
Ask HN: Best Documentation System? - flukus
So like many companies we don&#x27;t have a great deal of documentation for our systems and no culture of creating decent documentation, all we have is a few scattered word documents in sharepoint which are fairly useless. Lately I&#x27;ve got an opportunity to improve things however and I&#x27;m trying to find the right system to produce complex documentation in a variety of formats (word doc, web, maybe others), I&#x27;ve mainly been looking at plain text based ones because they interact well with tools like graphviz for technical drawings and easy insertion of code samples. So far I&#x27;ve tried:<p>Latex: Probably the most powerful&#x2F;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.<p>Markdown: Simple and ubiquitous, can output to just about any format, but a lack of support for many things like a glossary and ToC.<p>Texinfo: looks promising but I haven&#x27;t put any research into it yet so I&#x27;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.<p>Word&#x2F;Sharepoint: Horrible to work with, probably somewhat responsible for our lack of documentation.<p>Doxygen: I&#x27;ve used it in the past but it seems to be mostly geared toward API&#x2F;inline documentation, most of what I&#x27;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.<p>At the moment it looks like Texinfo and Doxygen are the two to investigate, but I&#x27;d like to hear the opinion of HN members on them and to let me know of any other options.
======
zapperdapper
A lot depends on your target audience, type of documents you are creating, and
also who the people writing the content are.

There 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://docusaurus.io/)

------
dazmiller
I use mkdocs. [https://www.mkdocs.org/](https://www.mkdocs.org/) very nice,
fast and easy to use

~~~
dazmiller
and this material theme

[https://squidfunk.github.io/mkdocs-
material/](https://squidfunk.github.io/mkdocs-material/)

Looks good, searchable, etc, etc, i think it produces some nice docs very
easily

