Guide to carry out this change and a comparison between them
Photo of melancholy activated unsplash
“A project is only as good as its documentation,” a quote from my previous 3-part article series that emphasizes the importance of documentation. Since then I have learned that there are different types of documentation, the most common are:
Technical documentation: Describe the technical aspects of the internal operation of the project, it can be process documentation or product documentation.Business documentation: Describe what business problems they solve or what business goals they achieve
There is a type of documentation that falls in between, these are manuals, guides and tutorials. This is especially important if you want to technical users to work on or use your project, or business users to understand your project and gain buy-in.
As documentation becomes more complex with more content, it can be difficult to display it in one easy to use and readable format. For example, tutorials should not be embedded in technical documentation, and ideally there should be a separate tab or navigation section between them.
This made me explore more Sphinx themes to make my documentation more beautiful and to be able to manage more information. I ended up being attracted Sphinx-Material i Sphinx-Immaterial themes that implement the MkDocs Material theme. After many tweaks, and still not getting the results I wanted, I changed MkDocs and finally understood the hype about MkDocs.
Having tried several methods and documentation topics, I will try to compare them, focusing on the features won and lost of switching from Sphinx to MkDocs. Finally, this article will end with important MkDocs settings to incorporate for more optimal documentation!
note: If you are interested, this is the one link in my documentation made with the Sphinx-Material theme, and this is the link to the same documentation made with MkDocs 🙂
[ad_2]
Source link
