We are developing a series of tools for our internal usage (only). We are writing the documentation in parallel with the development progress.

Is it important to provide different documentation formats? For the moment we generate the documentation only in HTML

  • 7
    Important to whom? I'm not being flip: the purpose of documentation is defined by its audience. What do you envision the purpose of other formats being? – CPerkins Aug 19 '16 at 20:40

If you are generating the documentation, just generate it in the format you need today. If you need it in a different format tomorrow, generate it in a different format tomorrow.

See also Yagni.

| improve this answer | |

Going from "no documentation" to "documentation in HTML" is a huge improvement. Going from "documentation in HTML" to "documentation in HTML and PDF" is a very tiny additional improvement, but may involve a lot of work. I'd rather you spend that work on improving the HTML documentation or adding more HTML documentation.

If someone says "I prefer documentation in PDF instead of HTML", your answer should be "Well, tough". If someone says "XYZ is not documented yet", the answer should be "I'll do it right now". (Obviously a bit exaggerated).

| improve this answer | |

The important thing is you pick a documentation format which is easily maintainable and can be used as a source for all the formats you want to support in the future (utilizing a generator tool chain).

There are different options depending on what kind of documentation you have in mind: if the tools you are going to document are actually library functions with an API, tools like Javadoc or Doxygen might be suited well. If, however, you are talking about programs with a user interface and end user documentation, tools like Asciidoc or Docbook might be better. But whatever you pick, what you IMHO should avoid like hell is to maintain the same documentation twice in two different formats.

| improve this answer | |
  • Asciidoc format made a big deal improvment in our projects due to the many formats it can be exported to. We generate asciidoc documents and we deliver PDFs to customers. At the same time an html versión of the document is packaged within the project as guide for users. – Laiv Sep 11 '16 at 15:43

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.