Documentación del software : manuales de usuario impresos, documentación en línea (online) y texto de ayuda que describe cómo usar el producto de software [1] .
Documento : un elemento de documentación: información específica destinada a un público específico, colocada en un medio específico (por ejemplo, en un libro, en un disco, en una tarjeta de referencia rápida) en un formato determinado [1] .
Documentación del programa - documentos que contienen, según el propósito, los datos necesarios para el desarrollo, producción, operación, mantenimiento de un programa o herramienta de software [2] .
Hay cuatro tipos principales de documentación de software:
La documentación de diseño generalmente describe el producto en términos generales. Sin describir cómo se usará algo, más bien responde a la pregunta "¿por qué es así?". Por ejemplo, en un documento de diseño, un programador podría describir la justificación de por qué las estructuras de datos están organizadas de la forma en que están. Se describen las razones por las que una clase está diseñada de cierta manera, se destacan los patrones y, en algunos casos, incluso se dan ideas sobre cómo se pueden realizar mejoras en el futuro. Nada de esto está en la documentación técnica o del usuario, pero todo es realmente importante para el proyecto.
Al crear un programa, el código por sí solo no suele ser suficiente. Se debe proporcionar algún texto que describa varios aspectos de lo que hace exactamente el código. Dicha documentación a menudo se incluye directamente en el código fuente o se proporciona con él.
Dicha documentación es de naturaleza muy técnica y se utiliza principalmente para definir y describir API , estructuras de datos y algoritmos .
A menudo, al compilar documentación técnica, se utilizan herramientas automatizadas: generadores de documentación , como Doxygen , javadoc , NDoc y otros. Toman su información de comentarios con formato especial en el código fuente y crean manuales de ayuda en algún formato, como texto o HTML .
Muchos programadores han encontrado que el uso de generadores de documentación y comentarios de documentación es una herramienta conveniente, por varias razones. En particular, con este enfoque, la documentación es parte del código fuente y se pueden usar las mismas herramientas para construir el programa y construir la documentación para él al mismo tiempo. También facilita el mantenimiento de la documentación al día.
A diferencia de la documentación técnica, que se enfoca en el código y cómo funciona, la documentación del usuario solo describe cómo usar el programa.
Si el producto es una biblioteca de software , la documentación del usuario y la documentación del código se vuelven conceptos muy parecidos, casi equivalentes. Pero en general, este no es el caso.
Por lo general, la documentación del usuario es un manual de usuario que describe cada función del programa, así como los pasos a seguir para usar esa función. Una buena documentación del usuario va más allá y proporciona instrucciones sobre qué hacer si surgen problemas. Es muy importante que la documentación no sea engañosa y esté actualizada. El liderazgo debe tener una estructura clara; muy útil si hay un índice transversal . La coherencia lógica y la simplicidad también son de gran importancia.
Hay tres enfoques para organizar la documentación del usuario. La guía introductoria , más útil para los nuevos usuarios, lo guía a través de una serie de pasos para completar algunas tareas comunes. Un enfoque temático, en el que cada capítulo del manual se centra en un tema en particular, es más adecuado para usuarios avanzados. En el último, tercer enfoque, los comandos o tareas se organizan como una referencia alfabética, a menudo bien recibida por usuarios avanzados que saben bien lo que están buscando. Las quejas de los usuarios generalmente se relacionan con el hecho de que la documentación solo cubre uno de estos enfoques y, por lo tanto, se adapta bien a solo una clase de usuarios.
En muchos casos, los desarrolladores de productos de software limitan el conjunto de documentación del usuario únicamente al sistema de ayuda integrado ( ayuda en línea en inglés ), que contiene información de ayuda sobre comandos o elementos de menú. El trabajo de educar a los nuevos usuarios y apoyar a los usuarios en evolución se deja en manos de los editores privados, quienes a menudo brindan una asistencia significativa a los desarrolladores.
Para muchas aplicaciones, es necesario tener materiales promocionales junto a ellos para interesar a las personas llamando su atención sobre el producto. Esta forma de documentación está destinada a:
Una de las buenas prácticas de marketing es proporcionar un eslogan , una frase simple y pegadiza que ilustre lo que queremos transmitir al usuario, además de describir la sensación que crea el producto.
A menudo sucede que la caja del producto y otros materiales de marketing brindan una imagen más clara de las posibilidades y formas de usar el programa que cualquier otra cosa.
| Desarrollo de software | |
|---|---|
| Proceso |
|
Conceptos de alto nivel | |
| Direcciones |
|
| Metodologías de desarrollo | |
| Modelos |
|
Figuras notables |
|