Existen diferentes tipos de documentación de software. Con el fin de facilitar su comprensión, personalmente los clasifico según tres dimensiones:
Un elemento es un concepto o componente del sistema.
Ejemplos de elementos pueden ser: requisitos, código, procesos, errores, funcionalidades, etc.
Dependiendo del elemento, la documentación puede variar en forma y contenido. Por ejemplo, la documentación de un proyecto puede incluir cronogramas, diagramas, listas de tareas, etc. Mientras que la documentación del código puede ser tan simple como un comentario en el código fuente.
El perfil define el conocimiento que se espera que tenga el lector del documento.
Ejemplos de perfiles pueden ser:
-
Expertos: personas que conocen la arquitectura del proyecto y diseñan el producto.
-
Desarrolladores: personas que construyen y mantienen los componentes del producto.
-
Técnicos: personas que deben conocer y usar el producto.
-
No técnicos: personas ajenas al proyecto que tienen curiosidad por aprender algo específico.
-
Ejecutivos: personas que toman decisiones comerciales, económicas, administrativas, legales, gubernamentales y/o políticas sobre el proyecto.
Entender el perfil del lector es importante para determinar la forma en que se debe presentar la información. Por ejemplo, cuando leemos una publicación en el periódico acerca de alguna investigación, este artículo debería utilizar un lenguaje dirigido a un público no especializado. Por otro lado, el informe de la misma investigación para científicos o profesionales del tema tendrá un enfoque distinto.
Una correcta documentación debe tener en cuenta las fórmulas:
buen documento = contenido relevante + formato adecuado + lenguaje entendible
buen contenido = lo que el lector necesita saber - lo que el lector sabe
buen formato = presentación agradable + estructura fácil de navegar
buen lenguaje = emplear palabras que el lector entienda
Un documento puede tener dos tipos de propósitos: descriptivo o prescriptivo. Un documento descriptivo presenta el estado actual del sitema. Un documento prescriptivo define cómo debe ser o cómo se debe usar el sistema.
Ejemplos de propósitos descriptivos pueden ser:
- Especificación: detalles de las características del producto.
- Casos de uso: detalles de las funcionalidades del producto.
- Versiones: historial de cambios del producto.
Ejemplos de propósitos prescriptivos pueden ser:
- Diseño: plan de cómo se debe construir el producto.
- Instalación: manual de cómo se debe instalar el producto.
- Uso: manual de cómo se debe usar el producto.
Es importante tener en cuenta que un mismo documento puede variar en su propósito según el estado del producto. Por ejemplo, la especificación del diseño del sistema puede ser considerado prescriptivo si aún no sea construído pero descriptivo tras el desarrollo.