So like many companies we don'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've got an opportunity to improve things however and I'm trying to find the right system to produce complex documentation in a variety of formats (word doc, web, maybe others), I'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've tried:
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.
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.