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.