Documentation

Documentation is tedious to write but having the right tools and frameworks can make the experience a lot easier.

Most of the documentation I’ve written has coincided with my project repositories on Github, so naturally I find myself writing notes in the Github wiki. Github has some options to improve the style of the wiki but sometimes it isn’t quite enough.

There are lots of different frameworks for documentation. Some examples include Sphinx, Jekyll, and MkDocs which if you remember from the last post are static site generators. Since Github wikis are markdown based and MkDocs was built with markdown in mind, MkDocs is my preferred choice.

These are the MkDocs themes I recommend:

• Read the Docs
• Material for MkDocs

If you started with a Github wiki and want to use a static site generator like Mkdocs, there are a few ways to accomplish that:

• continue to make your edits on the Github wiki and sync it with MkDocs
• migrate your wiki to its own repository
• migrate your wiki somewhere else

For the purpose of the following guides we’ll assume we are still going to be using Github for editing and/or hosting our documentation.

Instead of going through the tedious installation and configuration process here, I’ve added the documentation for setting up both themes below so you can see what they look like in practice.

• Read the Docs
• Material for MkDocs