Esta vez quiero hablar de una de las peores partes del desarrollo de software: la documentación. Junto al testeo es con diferencia lo más aburrido que puede hacer un programador. Y me apuesto algo a que todo el que sepa de lo que hablo, me dará la razón, seguro. 
Ya lo pone en el título: hay empresas que no saben ni qué es, otras que por falta de tiempo o ganas prefieren pasar de largo, y otras que se limitan a meter un críptico comentario cada 900 líneas. Por suerte, están también las que le dan la importancia que merece, y por suerte (de nuevo), me encuentro en una de ellas (o, al menos, en el departamento correcto xD). 
Tras haberme cepillado el 90% de los tickets pendientes, toca ponerse con uno de los últimos: el que hoy nos ocupa. Y ahí llegan las dudas: ¿qué metodología debo seguir? ¿qué debería tener una buena documentación?
Como bien me dijo mi amigo Manuel en su momento, hay una premisa que debemos tener clara: escribir el documento que nos gustaría encontrar si llegásemos de nuevas. No obstante, se echan de menos unas pautas que nos ayuden a confeccionar un texto uniforme y correctamente estructurado. Pero, como en todo, el sentido común dicta ciertas reglas que debemos seguir (bajo mi punto de vista):
- Incluir un índice recopilatorio.
- Explicar cuál es el cometido del programa (si se complementa con diagramas y demás, mejor).
- Si existe la posibilidad, explicar cómo se configura el mismo.
- Informar de los cambios entre versiones.
- Recopilar los bugs detectados.
- Utilizar una escritura directa y concisa.
- Mostrar ejemplos de uso y, en caso de ser código, indentarlos correctamente.
- Explicar el comportamiento ante errores.
- No desviarnos del tema, haciendo que cada apartado tenga su propia identidad.
- Si es necesario, aportar enlaces a otra documentación relevante.
- Tener en cuenta el idioma del target (si es muy amplio, hacer una versión en inglés).
- Permitir la modificación de cada parte lo más fácilmente posible.
- No utilizar estilos que nos distraigan de la lectura.
- Y por último, poner a disposición todo este contenido en varios formatos (HTML, PDF, CHM, etc).
¿Y vosotros qué, añadiríais alguna? 
).