Need to choose a suitable language to write documentation in

Question

Currently the documentation where I work is in a bit of a state. There isn't anywhere near enough of it, and the documentation that does exist is spread out over many word documents making it hard to find anything.

I'm trying to take some initiative and get it improved, and I figure the first thing is to find a better format to write the documentation in:

• My thoughts are that the documentation should be structured in a series of short articles (MSDN / Html Help style) and structured in a suitable tree:
  • It would be good to be able to produce a standalone Html-Help style package to be shipped with the application
  • As well as being able to produce a MSDN-style website as a reference for those who are too lazy to look at the CD.
  • Search is of course a must-have
• It needs to be at least reasonably easy to update - if there is a 17 step process to update the published documentation then it makes it seem like too much work to do simple changes, and nobody can ever be bothered to update it.
• The documentation is technical in nature, and so ideally it would be nice to be able to include generated documentation from things like the Xml documentation embedded in C# code. This is however definitely a side-requirement - currently very little useful Xml documentation exists, its just that in the future I plan to fix that.
• For the same reason it is often good to be able to handle things like attachments (code samples etc...) I'm not expecting anything fancy, but this is something I need to bear in mind to make sure that its at least not handled badly.

Are there any projects or languages that are suited to this sort of documentation?

Answer 1

If you use LaTeX you can get all your documentation in great looking PDFs and printed copies, as well as being able to generate html (via latex2html). TeX has the advantage of being all plaintext, too, so you can track/merge it reliably with your favourite revision control system.

Answer 2

We use confluence as our documentation repository. It is fairly easy to have public and private sections, and has a nice WYSIWYG editor. It can handle attachments and can be saved off as PDF documents if you like.

Answer 3

I've had good results with doxygen on my C and C++ projects although it supports many other languages as well. You put the documentation in comments in the code that can be simple or complex HTML markup. It is very easy to update as it is part of the code. You can make building the documents part of your build process. Additional topic that are not strictly API related can be added as separate HTML documents. The version I'm using doesn't support search so you would have to add another product to search these pages. Because it is HTML you can add in code samples, diagrams, etc.

Answer 4

I've used robohelp with good results. it is plain html, but has a generation process that keeps everthing looking consistent. It can be packaged as a .hlp file with the app, or published to the website. Check it out, it is simple so you can get back to doing your job :)

Answer 5

A clean way is to use DocBook. It is easy write and undetstand. It is also easy to parse as XML parsers are standard and other forms of documentation (e.g. from the embedded documentation in comments) can be easily be transformed to this format.

It is straightforward to generate PDF, HTML og other formats from the DocBook source (tools exist for this purpose).

Answer 6

I've started using DokuWiki. Its not exactly what I was originally looking for (I think I was really looking for a CMS), but it does the job and some respects its better than what I originally had in mind (in particular its a wiki - I've not yet gotten as far as publishing this to our customers however so I'm not sure how well thats going to work out)

I'm using the IndexMenu plugin and the Arctic template to get a navigation tree on the left, and if I publish the wiki itself I'll use the discussion plugin to allow users to post feedback.

Currently my method of handling generated content is to use xslt templates to produce dokuwiki syntax, and write that output directrly to files / folders in the "data/pages" folder.