javadoc

¿Cómo elaborar documentación técnica? Consejos.

Durante el proceso de elaboración de software se genera mucha, pero que mucha documentación. Yo como ingeniero de testing he leído muchos documentos de muchos programadores, analistas, jefes de proyecto, etc. Y lo que tengo claro es que es mejor no generar ningún tipo de documentación que generar documentación inservible o poco útil.

Durante el proyecto se genera mucha documentación pero también antes y después. La documentación de un programa o producto va dirigida a muchas personas como programadores, usuarios, personas que van a testear la aplicación, etc.

Lo más importante de la documentación como decía antes es que sea de calidad. Alguna de la documentación que se genera en proyectos informáticos en ocasiones carece de calidad. Se suele ver mucho en los manuales de usuario. Muchas veces, este tipo de manuales se encargan de describir obviedades de las ventanas o interfaces que cualquier usuario medio puede intuir delante del programa y omiten información importante que es de utilidad.

La mayoría de las veces esta falta de calidad viene dada porque el tiempo que se le dedica a la documentación es escaso. Y en ocasiones, a los programadores no nos gusta crear documentación y lo hacemos de mala gana y luego eso se traduce en un pésimo resultado.

Al final, si la documentación no tiene calidad nunca va a servir como referencia y no se le dará ningún uso.

A continuación se muestran ciertas pautas para escribir documentación de calidad:

  • Haz siempre esquemas antes de ponerte a escribir. Puedes también incorporar dichos esquemas a tus manuales.
  • Clasifica la información según importancia. Es mejor tener un buen documento principal y muchos anexos que un documento principal muy grande.
  • 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.
  • Muchos lenguajes de programación, ellos mismos tienen sus propios estándares y herramientas de documentación. Si es así es mejor utilizarlos. Por ejemplo Java tiene Javadoc.
  • A la hora de escribir la documentación para el usuario hay que anticiparse y responder a las preguntas que se pueda hacer el usuario o lector. Habrá que responder a preguntas como: ¿y ahora después qué hago? ¿Qué hace este botón? ¿Qué implica borrar esto o aquello? etc.
  • Es importante la claridad a la hora de escribir documentación de usuario. Hay empresas de software a las que les gusta utilizar segunda persona (“tú”) en vez de tercera persona (“el usuario”). Yo particularmente prefiero la tercera persona pero antepongo a esto la claridad.
  • Hay que elegir bien la herramienta de documentación. En ciertos casos el obcecarse con herramientas como procesadores de textos hace difícil de seguir el hilo a la documentación de distintos programas y módulos, quizás sería mejor utilizar herramientas hipertextuales o herramientas que facilitan la documentación del código como HelpLogix, RoboHelp, Doc-To-Help, etc. No desechar herramientas colaborativas como wikis, google docs, y demás.
  • Muchas veces se generan dos documentos de usuario para el software. La guía de usuario y el manual de referencia. Un manual de referencia explica el software de una forma más en profundidad. En ocasiones, este manual de referencia se distribuye como ficheros de ayuda dentro de la propia aplicación. La guía de usuario es más sencilla y explica cómo realizar paso a paso ciertas tareas con el software. Suelen tener formato de tutorial.
  • Hay que tener en cuenta el nivel del usuario que va a leer la documentación. En estos documentos hay que dejar claro qué es lo que el usuario no debe ni puede hacer, las consecuencias de ejecutar algo, qué ocurre si no se hace algo, etc.
  • Realiza un checklist en el cual cualquier programador puede cumplimentarlo y ver si realmente está generando documentación de calidad para un proyecto. No te bases solamente en este artículo sino que tendrás que investigar más sobre la creación de documentación en proyectos software.

    One thought on “¿Cómo elaborar documentación técnica? Consejos.

    Deja un comentario

    Tu dirección de correo electrónico no será publicada. Los campos necesarios están marcados *

    Puedes usar las siguientes etiquetas y atributos HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>