Best way to write documentation.

Question

I need to create some documentation for a project that will evolve in the future. The documentation will grow huge, so I need to choose some proper tools.

The proper documentation tool should:

1. Store everything in plain text files (so I can make diffs without any problems).
2. Easily convert all files to linked html (with many pages) and (maybe) to pdf.
3. Enable to link and include one file into another while creating the output html.
4. Be easy to learn for a newcommer.

What should I choose?

Answer 1

I like using PHPDOC http://www.phpdoc.org/ since I can document everything myself as I am coding - then you have the option to use another product afterwards should you choose.

• What language are you coding in?
• And who is the documentation for (and what kind of documentation, techincal or how tos)?

Answer 2

Sphinx is very nice.

Answer 3

We use Docutils reStructuredText (a LaTex frontend); that gives you your .txt source. Then I wrote a Python tool to create all of the HTML/PDF formats you're looking for, including the 3-frame SDK-style HTML documentation with table-of-contents, index and search capabilities. I read an XML file that specifies the source to be included in the document. It's all very automated and runs as part of the build.

It works and you'll probably like it but I don't recommend that approach. Documentation is best completely separated from software development unless it is fully integrated into your software development methodology, which is quite rare these days (the foremost and obvious reason being that most developers don't write). But if your project is small enough and you have complete control over all of it, the way we do it will work for you also. The number of pages has little to do with complexity and you probably won't run into scaling issues for a long time, if ever. The number of dependencies between pages is a much more important parameter, which will become nearly unmanageable after only about seven pages.