How to develop high quality documentation.
During, before and after the development of a software, a lot of documentation is generated. I was testing engineer some years ago and I have read lots of documents from programmers, analyst, project manager, etc.
From my point of view, it is better not to elaborate any documentation than generate useless or poor documentation.
It is very important to generate high quality documentation. Sometimes this lack of quality can be seen in user documents. A lot of times, the document does not help the user to understand the software.
As always, the programmer does not have the fault of this lack of quality because he has no time to generate good documentation. Occasionally, programmers does not like to write documentation and their bosses does not like to revise it and the result of that is a useless documentation.
A documentation without quality is useless.
Let us see some advices to write high quality documentation:
You should make schemes/diagrams before writing. You should add those schemes/diagrams in your documents.
Classify the information by importance. Is better to write a good main document and multiple annexes than a big single main document.
Realiza resúmenes, esquemas, documentos maestros etc. Siempre es bueno hacer un trabajo de síntesis en el que se explique el conjunto de la documentación.
Lots of programming languages have their own documentation tools. For example you can use Javadoc in Java language.
Clarity is important when you are writing user documentation. Some software companies prefer to use third person when writing, others first person. I particularly prefer third person but take into account that clarity is more important than that.
YYou have to take your time in choosing the documentation tool. The text processors sometimes are not the best tool to write documentation for programs and modules. Sometimes is better to use hypertext tools or other specific tools like HelpLogix, RoboHelp, Doc-To-Help, etc. You can also use tools like wikis, google docs, and others.
In many projects, programmers write two documents: the user guide and the reference guide. The reference guide is bigger than the first one and explains the software more thoroughly than the user guide. Sometimes programmers use to deliver the reference guide in files instead of printing a document. The user guide is more user friendly and explains how to manage the software step by step. They are like a tutorial.
You should have in account the user level that is going to read the documentation. Take care explaining what the user should not do, what happen if the user executes that process, etc.
Resumen
Nombre del artículo
How to develop high quality documentation.
Descripción
During, before and after the development of a software, a lot of documentation is generated. In this post we explain how to write high quality documentation.
Autor
Juan Carlos Moreno
