Ask HN: Best Documentation System?
Latex: Probably the most powerful/flexible but only really good at producing PDFs. Horrible error messages, no doc output and bad copy paste support (code snippets) are the biggest downsides that made me look at other options.
Markdown: Simple and ubiquitous, can output to just about any format, but a lack of support for many things like a glossary and ToC.
Texinfo: looks promising but I haven't put any research into it yet so I'm not aware of downsides. Single page html output would be good for converting to doc and the GNU documentation is very nice, a seemingly sane table format.
Word/Sharepoint: Horrible to work with, probably somewhat responsible for our lack of documentation.
Doxygen: I've used it in the past but it seems to be mostly geared toward API/inline documentation, most of what I'm writing is higher level than that, but integrating with the code could be nice. It also seems to rely on authors to supply their own structure. Probably worth investigating further and living in the source repository is a positive.
At the moment it looks like Texinfo and Doxygen are the two to investigate, but I'd like to hear the opinion of HN members on them and to let me know of any other options.
3 comments
[ 4.1 ms ] story [ 21.6 ms ] threadThere is no "best" documentation system really, only what's best for your requirements. For example, in some cases DITA XML may be absolutely the best choice, in other cases LaTeX makes more sense, it just depends.
If you are documenting APIs take a look at OAS3.
Cross Word off your list unless you needs are very small scale - even Microsoft use Markdown/GitHub for their tech docs these days.
Personally, I would probably go for Markdown/GitHub/GitLab and use some third party tools for TOC generation. A static doc site generator like Docusaurus[1] might provide what you need. But as I say difficult to tell without knowing all the details. Good luck!
[1] https://docusaurus.io/
https://squidfunk.github.io/mkdocs-material/
Looks good, searchable, etc, etc, i think it produces some nice docs very easily