3 ms·
Other people mentioned code comments and Markdown files, I'm inclined to agree. I've used code comments pretty well to explain both non-trivial technical detai
by KronisLV 4y ago
Other people mentioned code comments and Markdown files, I'm inclined to agree.
I've used code comments pretty well to explain both non-trivial technical details, as give a quick rundown of business requirements that are the basis for some code existing, maybe with links back to an issue tracking system where more context is needed. Markdown files are better if you want to include images/videos/animations/diagrams and provide more context, or step by step instructions on how to do something, which is great because you can easily search through them, as they're just text. Code can typically explain what it does itself but not necessarily why, so it's great to have either of the tools at your disposal.
Of course, there's nothing wrong with external Wikis either, though some are implemented better than others IMHO.
Confluence is sometimes the only choice you get, so having it is better than having nothing.
GitLab and GitHub also have integrated Wikis, as do other solutions: https://docs.gitlab.com/ee/user/project/wiki https://docs.gitlab.com/ee/user/project/wiki and https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis https://docs.github.com/en/communities/documenting-your-proj...
For ones to host separately, I've found BookStack to be pretty good in its simplicity/usability/performance: https://www.bookstackapp.com/ https://www.bookstackapp.com/
As for things that are meant specifically for documentation, Read the Docs might be of appeal to some: https://readthedocs.org/ https://readthedocs.org/
You can probably also use Sphinx (used by Flask): https://www.sphinx-doc.org/en/master/ https://www.sphinx-doc.org/en/master/ or MkDocs: https://www.mkdocs.org/ https://www.mkdocs.org/ or something else entirely.