I've been trying to write a documentation page for my project (An android app to control your VLC media player) for a very long time. I decided to use some static site builders to get it done quickly.
I am already using gatsby for my blog. I thought of building my gatsby theme as I am pretty much satisfied by Gatsby. but it takes lots of time.
In this post, I will share my opinions on documentation tools that I have considered for my project.
My requirements are:
- Appearance should align with my product theme.
- It should be user friendly as I am going to use it for one of my android apps (not just for developers).
- It should be SEO friendly.
- Now I don't have any complex requirements. but it should be extendable in the future.
- It should be hostable in GitHub pages using a new repo other than my personal page repo. I didn't want to pollute my blog with docs logic as I might add few more docs for some other projects.
- It shouldn't require much configuration/learning for up and running.
- It should be simple.
Gatsby-docs-kit:
Pros:
- Based on gatsby.
- Easily customizable.
- We can host it on GitHub.
Cons:
- Too much to do for documentation.
- Not SEO friendly. but we can configure using plugins available for gatsby. (I didn't want to do that again for docs).
Docsify:
Pros:
- Easy to set up.
- Comes with four predefined themes. we can easily create our own themes using this tool.
- Configurable using plugins. we can write our plugins too.
- We can build it and host it GitHub.
Cons:
GitBook : (I want to try this in future):
Some sample sites using Gitbook Timber.
Pros:
- SEO friendly.
- No need to set up in our local machine. It is free for personal use.
- It comes with powerful analytics.
- Drag and drop UI.
- It requires less programming knowledge.
Cons:
- Vendor lockdown.
- We're limited by the customization they provide.
- We can't host it on our own.
Gitdocs:
I stumbled up this framework after seeing dev.to's documentation. It is very easy to configure. I felt some limitations from the beginning itself.
Pros:
- SEO friendly.
- We can build it and host it GitHub.
Cons:
- No theming support as of now.
- Not maintained very actively (The last commit was made 2 years back). I feel the development has been stopped.
- My primary GitHub page is https://gokuldroid.github.io. If I have another project the public URL will look like this https://gokuldroid.github.io/{project_name}. This setup is not easy with Gitdocs. There are open issues and PR related to this.
- Not customizable.
Daux.io
Some sample sites using this framework pixolution , soisy.
Props:
- It has multilingual support.
- We can build it and host it GitHub.
Cons:
- The default theme is not user friendly.
- There is no much documentation for customization. but some sites using this framework has a really good look and feel.
- Only the homepage and documentation page is available. we can't add custom pages.
- Not extendable.
MkDocs:
Pros:
- Very popular and actively maintained (10K stars in GitHub)
- Lots of predefined themes available.
- We can build it and host it GitHub.
Cons:
- Based on python might not work very well with other frontend tools.
Docusaurus:
There are two major versions of docusaurus. versions two is still in beta and it doesn't have some of the features of version one. but the road map of docusaurus 2 seemed interesting to me. So I wanted to give it a try for my blog.
Pros:
- It is maintained by Facebook.
- Easily themeable. It uses infima under the hood (Note: this also still in beta).
- It comes with a lot of predefined configurations.
- Lots of facebook's open-source projects use this for documentation.
- It has lots of flexibility.
- We can build it and host it GitHub.
Cons:
- Version 2 still in beta (but it is pretty much stable).
Based on the observations, I've decided to use docusaurus beta for my app's documentation. You can take a look at the final site here and source code here. Let me know, what is your personal choice in documentation tools and why.