Information on performing this change, and a comparability between them

“A mission is barely nearly as good as its documentation” — a quote from my earlier 3-part article sequence stressing the significance of documentation. I’ve since realized that there are completely different sorts of documentation, the extra widespread ones being:

1. Technical documentation: Describing the technical points of the mission’s internal workings, it may be course of documentation or product documentation
2. Enterprise documentation: Describing what enterprise issues it solves or enterprise goals met

There exists a kind of documentation that’s type of in-between, these are manuals, guides, and tutorials. That is particularly essential if you’d like technical customers to work with or use your mission, or enterprise customers to know your mission and get buy-ins.

Because the documentation will get extra advanced with extra content material, it may be tough to show it in a user-friendly and readable format. For instance, the tutorials shouldn’t be embedded inside the technical documentation, and there ought to ideally be a separate navigation tab or part between them.

This sparked me to discover extra Sphinx themes to make my documentation prettier and to have the ability to deal with extra info. I ended up being drawn to Sphinx-Materials and Sphinx-Immaterial themes which implement the Materials theme from MkDocs. After lots of tweaking, and nonetheless not getting the outcomes I needed, I switched to MkDocs and eventually understood the hype about MkDocs.

Having tried varied documentation strategies and themes, I’ll attempt to examine them — specializing in the options gained and misplaced from switching from Sphinx to MkDocs. Lastly, this text will finish with essential MkDocs settings to include for extra optimum documentation!

Observe: If , that is the hyperlink to my documentation made with the Sphinx-Materials theme, and that is the hyperlink to the identical documentation made with MkDocs 🙂