Evaluating documentation frameworks for personal projects.

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:

  • Not SEO friendly.

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.

« (Git autocompletion)(Show me your projects graveyard!) »