3 ms·
Honestly I think this is personal preference more than anything else, so I'm not sure how useful my answer is, but I thought I should at least try to answer you
by xolox 7y ago
Honestly I think this is personal preference more than anything else, so I'm not sure how useful my answer is, but I thought I should at least try to answer your question :-).
I have quite a few years of experience in using Sphinx to create high quality technical documentation for open source Python projects, which explains why I chose Sphinx for this endeavor in the first place, but that's not an answer to your question.
The following dichotomy that I feel exists may (?) be more useful:
* Wikis tend to grow organically without much restructuring. I don't think this is fundamental to any specific wiki system, more of an emergent behavior, if you will. Enough discipline can surely avoid this, but wiki systems don't exactly make it easy - I haven't seen many "refactoring" tools in wiki engines, though they probably exist (global rename that updates references, moving of sections of text between documents, etc). I have definitely seen quite a few wikis devolve into the documentation equivalent of a "big ball of mud".
* Sphinx being based on a simple directory structure of text files on a local filesystem in reStructuredText format makes it much easier for me to "refactor mercilessly" in order to adjust the structure of the documentation so it keeps making sense as it evolves (e.g. things as simple as "grep -r" and "find | xargs | sed -i" or equivalents built into editors). To make sure no references were harmed there is "sphinx-build -nW".
I've also grown to appreciate the value of generated content. For example we have a dozen software projects and another dozen internal web services. I cataloged both as a directory of simple CSV files that contain details like repository locations, programming languages and frameworks used, type of release management process used, etc. During the documentation build these CSV files are rendered into multiple output formats, for example an overview table that lists the most relevant high level details of each project / service and separately from that the more detailed information about each project / service. The data only needs to be entered once (DRY), but can be rendered any number of times.