The Importance of Centralizing
Writing documentation in the first place is a great first step towards making the software and ecosystem that you work on better. The next important step in documenting your work is to make that documentation available. If you go through all the effort to write clean and concise documentation but don't publish it in an easily accessible location, then it will be hard to get your audience to even read it. If no one can easily read your documentation, then it is not reaching its maximum potential.
In some cases, for example instructions for setting up a project repository, there is a natural place for your documentation - just add a README.md to the repository. GitHub and most other Git repository management tools automatically render your Markdown when you visit the repository. But what about when the documentation you write isn't about a particular application or repository - where would you put it in that case?
You could just throw it in some random Git repository and share the link, but then that link has a very high likelihood to get lost in Slack DMs or emails. A better solution is to create a dedicated and centralized place to store all documentation. This has many benefits:
- It creates a constantly updating collection of resources for your organization. All you need to do is bookmark the site and you'll get easy access to this collection forever.
- It eliminates the ambiguity in where to publish documentation. If anyone ever writes a document and has no idea where to publish it, they now have an easy answer: publish it to the centralized location!
- It gives individuals an obvious first place to go when they have a question. If your organization has thorough documentation, chances are the answer is there.
Piggybacking on the last point, if the documentation is thorough, then a centralized place for documentation can also help you deal with this scenario you probably encounter daily:
"Can you explain <insert business process> to me?"
When asked this question by a coworker, just respond with:
"You should be able to find it in our centralized documentation. If you read through it and are still confused, I'd be happy to further elaborate."
99% of the time, I never hear from those individuals again.
Getting started with Docsify & GitHub Pages
One of the best solutions for this centralization problem is Docsify & Github Pages. With these two tools, you'll be able to start a website to host your organization's documentation in no time.
Docsify is a tool that dynamically generates HTML files from Markdown files. This allows us to take advantage of all the benefits of Markdown to build a website very easily. To get started, check out Docsify's Quick Start guide. They provide a way to run a local environment so you can edit Markdown files and instantly see the resulting pages that Docsify generates for you.
GitHub Pages is an easy and free way to host your Docsify website. Docsify also has a deployment guide which you can follow to host your documentation site in minutes.
Why Docsify & GitHub Pages?
1. Docsify gives us all of the advantages of Markdown, combined with the ability to customize how your pages render. Markdown is the easiest way for developers to write down their thoughts, and Docsify fully supports the Markdown spec. There are also a variety of ways to customize your website built through Docsify:
- There are several configuration options built by the creators at Docsify.
- You can provide your own custom themes to customize the appearance of your pages.
- Docsify comes with plugin support as well. Check out this extensive list of plugins that are available for Docsify. If you can't find a plugin that accomplishes what you need, they also give you the option to write your own.
2. Hosting with GitHub pages gives you familiar source control with your documentation. This allows us to treat our documentation as we do our code. We can easily collaborate on the same page of documentation, and also have access to the entire history of a document. Additionally, hosting the Markdown files on GitHub allows for an easy review process, leveraging the same Pull Request process we use to review our code. This encourages more collaboration on writing documentation, something that I believe we can do more of as an industry.
3. Docsify is as simple as you need it to be. The flexibility of Docsify makes it very simple, yet extensible. If you just want to write some Markdown and render your pages, Docsify makes that very easy for you. If you'd like to customize your pages, Docsify enables that as well - it supports it. You can choose how deep you want to dive into the Docsify ecosystem.
Advanced Features
There are a few advanced features of Docsify that easily elevate your Markdown files into a full-fledged website.
Sidebar
One of the most useful built-in features of Docsify is the ability to create a sidebar for your documentation site. Better yet, you create the sidebar through syntax you already are familiar with - Markdown! Here is an example of a sidebar that we can define with Markdown:
<!-- docs/_sidebar.md -->
- [Home](/)
- [Learning HTML](html.md)
- [Learning CSS](css.md)
- [Learning JavaScript](js.md)
- [Learning Frontend Web Frameworks](frontend.md)
Having a sidebar turns your collection of Markdown files into a cohesive, navigatable central resource for your organization. It makes all the documents in your repository easily accessible from a nice web interface.
Tab Controls
One of the Docsify plugins I have used the most is docsify-tabs. This plugin allows you to easily build a customizable tab control from Markdown:
<!-- tabs:start -->
#### **React**
Facebook's frontend framework for building reactive, component-based user interfaces.
#### **Angular**
Google's frontend framework for building speedy and performant user interfaces with extensive built-in tooling.
#### **Vue**
Evan You's approachable and versatile frontend framework for building user interfaces.
<!-- tabs:end -->
The above Markdown renders into the following tab-based UI:
This is a very simple way to easily improve the readability of your simple Markdown files, without any additional effort. There are plenty of other plugins that you can bring into Docsify that have a similar effect. I encourage you to look through this list of Docsify plugins to see if any additional plugins will make your documentation even better.
If you liked this article and want to be notified when I publish another, consider subscribing to my mailing list.
Top comments (0)