Motivation
Any tools is only good if people can use it!
This makes documentation essential, if not one of the most important parts of any software product.
Building good documentation is not easyhard, and that's why it is often depioritized. Especially among the open-source,
resulting in many great projects remaining uderutilisednot used at all.
Well, it shouldn't be tlike this. And MkDocs Workspace is created to tackle this problem. It is probably one of the easiest way to develop and deploy awesome documentation websites.
Why documentation website?
Why would I make a separate documentation website? I document code in readme files of my git repository
- Github does not render extended markdown features like diagrams or formulas.
- In the case of closed-source software, sharing readme files from the git repository with external users is not an option.
- MkDocs website with beautiful themes looks much better than readme-files in the git repository.
- MkDocs adds text search to your documentation website.
- With MkDocs Workspace you create documentation from the same markdown readme files you have in your repo together with the code.
- With MkDocs Workspace you can easily create a single documentation website from multiple git repositories in Github, GitLab, Bitbucket, etc.
- You can easily add such features as Google Analytics, different languages, and separate documentation for different versions of the software product.
- The resulting documentation website looks professional and classy.
We use Confluent / Wiki together with GitHub for internal documentation
That's just terrible: having docs in different places. It creates chaos and divergence of documentation. And you never know where to look for the information you need.
The best docs live together with the code. With MkDocs Workspace you can follow this practice, and use the docs that you keep with the code in the same repositories, in order to create professional documentation website.