La creación de software y la realización de proyectos de creación de software implica la creación y gestión de la documentación asociada. Cada paso en la creación y producción de software supone la generación de documentación que se tiene que contemplar y gestionar. La correcta gestión de esta documentación permite controlar los proyectos, facilita la utilización por parte del usuario y disminuye los costes. El concepto de documentación de software comprende diferentes tipos de documentación e implica diferentes roles:
– Documentación de arquitectura/diseño: : Define las prácticas, técnicas y tipos de representaciones utilizadas por los arquitectos de software para registrar una arquitectura de software. Una de las ramas de la fase diseño de software implica la creación de un libro blanco sobre aspectos concretos del sistema, como la interfaz de diseño, el código, el documento de diseño, los elementos de diseño, etc., y es útil para los diseñadores, desarrolladores, administradores, etc. de las base de datos o aplicaciones.
–Documentación técnica: Acompaña al software y describe varios aspectos de su funcionamiento. Documenta el código, algoritmos, interfaces y API. La documentación técnica puede ser utilizada por los desarrolladores, probadores y también por los clientes finales o clientes. Varias herramientas, como Doxygen, Ndoc, RoboDoc, etc., permiten generar automáticamente documentación a partir del código fuente y crear manuales de referencia en formas como por ejemplo archivos de texto o HTML.
Captura de pantalla del projecte del sistema operatiu Chromium
– Requisitos de software: Los requisitos son la descripción de lo que un software hará o no hará y son declaraciones que identifican atributos, capacidades, características o cualidades de un sistema. Los requisitos afectan a todos los agentes involucrados en la producción: usuarios, clientes, gerentes, ventas, marketing, arquitectos de software, ingenieros de usabilidad, diseñadores de interacción, desarrolladores, etc. Se muestran en una variedad de estilos y notaciones y pueden ser especificados como declaraciones de lenguaje natural, fórmulas matemáticas, dibujos o todas ellas combinadas. La necesidad de documentación de los requisitos está relacionada con la complejidad del producto y su impacto.
– Documentación para el usuario final: Son los manuales para el usuario final, administradores de sistemas y personal de soporte, y explican cómo funciona el programa. El manual describe cada función del programa y ayuda al usuario, al tiempo que puede proporcionar asistencia para solucionar problemas más complejos. Es muy importante que los documentos de usuario estén al día. A pesar de que no necesitan estar organizados de una manera determinada, es importante que tengan un índice exhaustivo. La documentación del usuario se considera que constituye un contrato que especifica lo que el software hará. Las tres formas básicas de la documentación de usuario son el tutorial, el enfoque temático y la lista de referencia.
– Documentación de marketing: Para determinadas tipologías de software es necesario disponer de diferentes materiales promocionales. La documentación informa de lo que hace el producto exactamente e impele al posible comprador a su compra.
Software libre
En relación con la documentación de software libre, se considera que a menudo los manuales y la documentación disponible es incompleta o de baja calidad; es decir, a veces el problema no es el software libre en sí, sino la documentación que lo acompaña. Sin una documentación completa y fiable, el proceso de creación de software es incompleto. Como solución se propone la utilización de una licencia de software libre como la del sistema operativo GNU: https://www.gnu.org/licenses/fdl-1.3.en.html. GNU también ofrece en su página una lista de licencias libres para documentación de software: https://www.gnu.org/philosophy/license-list.html#FreeDocumentationLicenses.
Recursos sobre documentación de software
– Enlaces:
Beautiful docs: Lista colaborativa de recursos para la creación de documentación de software que se actualiza regularmente. Contiene enlaces para escribir documentación y herramientas para generar documentación.
Software Documentation.info: Extensa página dedicada a la documentación de software, ofrece herramientas y recursos para la documentación.
Categoria de documentació de programari a Viquipèdia: Incluye recursos y enlaces a programas, herramientas, proyectos y artículos sobre la documentación.
Yevgeniy Brikman. Youarewhatyou document. http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html. [Fecha de consulta: 1 de junio de 2014]: Amplio artículo que recoge multitud de enlaces y casos prácticos ordenados según categorías y temas. Es un artículo interesante para iniciarse en el tema.
A begginers guide to write documentation: Sitio web con información, recursos, foro de documentalistas que sirve como punto de encuentro de documentalistas de software. Periódicamente organizan encuentros profesionales y conferencias.
Perfiles de twitter que hablan sobre documentación:
Bibliografía:
McConnell’s, Steve. Code complete. A PracticalHandbook of Software Construction. 2a ed. EUA: Microsoft books, 2004. 960 p.ISBN-10: 0735619670.
Yevgeniy Brikman. You are what you document. http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html. [Accés: 1 de juny del 2014]: Ampli article que recull multitud d’enllaços i casos pràctics ordenats segons categories i temes. Software documentation.
http://en.wikipedia.org/wiki/Software_documentation. >. [Fecha de consulta: 30 de mayo de 2014].
Why Free Software needs Free Documentation. https://www.gnu.org/philosophy/free-doc.en.html. [Fecha de consulta: 1 de junio de 2014]. Documentació de programes en programari lliure.
http://www.eoi.es/wiki/index.php/Documentaci%C3%B3n_de_programas_en_Software_libre. [Data de consulta: 31 de maig del 2014]
Deja una respuesta