Switching From Sphinx to MkDocs Documentation — What Did I Gain and Lose?

Guide on performing this switch, and a comparison between them

Photo by melanfolia on Unsplash

“A project is only as good as its documentation” — a quote from my earlier 3-part article series stressing the importance of documentation. I have since learned that there are different kinds of documentation, the more common ones being:

1. Technical documentation: Describing the technical aspects of the project’s inner workings, it can be process documentation or product documentation
2. Business documentation: Describing what business problems it solves or business objectives met

There exists a type of documentation that is kind of in-between, these are manuals, guides, and tutorials. This is especially important if you want technical users to work with or use your project, or business users to understand your project and get buy-ins.

As the documentation gets more complex with more content, it can be tricky to display it in a user-friendly and readable format. For example, the tutorials should not be embedded within the technical documentation, and…