Documentación del software

La documentación de requisitos describe lo que un software hace o debería hacer. Se utiliza durante todo el desarrollo para comunicar cómo funciona el software o cómo se supone que debe funcionar. También sirve como acuerdo o como base para un acuerdo sobre las funciones del software. Los requisitos son elaborados y utilizados por todos los involucrados en la producción de software, incluyendo: usuarios finales , clientes , gerentes de proyecto , ventas , marketing , arquitectos de software , ingenieros de usabilidad , diseñadores de interacción , desarrolladores y evaluadores .

Los requisitos se presentan en diversos estilos, notaciones y niveles de formalidad. Pueden ser objetivos (por ejemplo, un entorno de trabajo distribuido ), estar relacionados con el diseño (por ejemplo, las compilaciones se pueden iniciar haciendo clic con el botón derecho en un archivo de configuración y seleccionando la función "compilar" ) o cualquier punto intermedio. Se pueden especificar mediante enunciados en lenguaje natural , figuras gráficas, fórmulas matemáticas detalladas o una combinación de todos ellos.

La variabilidad y complejidad de la documentación de requisitos la convierten en un desafío comprobado. Los requisitos pueden ser implícitos y difíciles de descubrir. Es difícil determinar con exactitud cuánta y qué tipo de documentación se necesita y cuánto se puede dejar a la documentación de arquitectura y diseño, y es difícil saber cómo documentar los requisitos considerando la diversidad de personas que leerán y utilizarán la documentación. Por lo tanto, la documentación de requisitos suele estar incompleta (o ser inexistente). Sin una documentación de requisitos adecuada, los cambios de software se vuelven más difíciles y, por consiguiente, más propensos a errores (disminución de la calidad del software ) y más costosos.

La necesidad de documentación de requisitos suele estar relacionada con la complejidad del producto, su impacto y la vida útil del software. Si el software es muy complejo o ha sido desarrollado por muchas personas (por ejemplo, software para teléfonos móviles), los requisitos pueden ayudar a comunicar mejor los objetivos. Si el software es crítico para la seguridad y puede tener un impacto negativo en la vida humana (por ejemplo, sistemas de energía nuclear, equipos médicos, equipos mecánicos), a menudo se requiere una documentación de requisitos más formal. Si se espera que el software tenga una vida útil de solo uno o dos meses (por ejemplo, aplicaciones móviles muy pequeñas desarrolladas específicamente para una campaña determinada), es posible que se necesite muy poca documentación de requisitos. Si el software es una primera versión que se actualiza posteriormente, la documentación de requisitos es muy útil para gestionar los cambios y verificar que no se haya producido ningún fallo al modificarlo.

Tradicionalmente, los requisitos se especifican en documentos de requisitos (por ejemplo, mediante procesadores de texto y hojas de cálculo). Para gestionar la creciente complejidad y la naturaleza cambiante de la documentación de requisitos (y de la documentación de software en general), se recomienda el uso de sistemas basados ​​en bases de datos y herramientas específicas para la gestión de requisitos .

En el desarrollo de software ágil, los requisitos suelen expresarse como historias de usuario con sus respectivos criterios de aceptación. Las historias de usuario suelen formar parte de una funcionalidad o épica, que es una funcionalidad más amplia o un conjunto de funcionalidades relacionadas que aportan un valor específico al usuario en función de los requisitos del negocio.

La documentación de arquitectura (también conocida como descripción de la arquitectura de software ) es un tipo especial de documento de diseño. En cierto modo, los documentos de arquitectura son la tercera derivada del código ( los documentos de diseño son la segunda derivada y los documentos de código, la primera). Muy poca información en los documentos de arquitectura es específica del código. Estos documentos no describen cómo programar una rutina determinada, ni siquiera por qué existe una rutina en la forma en que lo hace, sino que simplemente enumeran los requisitos generales que justifican su existencia. Un buen documento de arquitectura es conciso en detalles pero extenso en explicaciones. Puede sugerir enfoques para el diseño de bajo nivel, pero deja los estudios comparativos de exploración propiamente dichos para otros documentos.

Otro tipo de documento de diseño es el documento comparativo o estudio de viabilidad. Este suele adoptar la forma de un informe técnico (whitepaper) . Se centra en un aspecto específico del sistema y sugiere enfoques alternativos. Puede abarcar la interfaz de usuario , el código, el diseño o incluso la arquitectura. Describe la situación, presenta una o más alternativas y enumera las ventajas y desventajas de cada una. Un buen estudio de viabilidad se basa en una investigación exhaustiva, expresa su idea con claridad (sin recurrir a jerga compleja para deslumbrar al lector) y, sobre todo, es imparcial. Debe explicar con honestidad y claridad los costes de la solución que propone como la mejor. El objetivo de un estudio de viabilidad es idear la mejor solución, no imponer un punto de vista. Es aceptable no llegar a una conclusión o concluir que ninguna de las alternativas es suficientemente mejor que la solución de referencia como para justificar un cambio. Debe abordarse como un esfuerzo científico, no como una técnica de marketing.

Una parte fundamental del documento de diseño en el desarrollo de software empresarial es el Documento de Diseño de Base de Datos (DDD). Este contiene elementos de diseño conceptual, lógico y físico. El DDD incluye la información formal que necesitan las personas que interactúan con la base de datos. Su propósito es crear una fuente común que puedan utilizar todos los participantes. Los usuarios potenciales son:

• Diseñador de bases de datos
• Desarrollador de bases de datos
• Administrador de bases de datos
• Diseñador de aplicaciones
• Desarrollador de aplicaciones

Cuando se habla de sistemas de bases de datos relacionales , el documento debe incluir las siguientes partes:

• Esquema entidad-relación ( mejorado o no), incluyendo la siguiente información y sus definiciones claras:
  • Conjuntos de entidades y sus atributos
  • Las relaciones y sus atributos
  • Claves candidatas para cada conjunto de entidades
  • Restricciones basadas en atributos y tuplas
• Esquema relacional, que incluye la siguiente información:
  • Tablas, atributos y sus propiedades
  • Vistas
  • Restricciones como claves primarias, claves foráneas,
  • Cardinalidad de las restricciones referenciales
  • Política en cascada para restricciones referenciales
  • Claves primarias

Es fundamental incluir toda la información que utilizarán todos los actores en la escena. Asimismo, es crucial actualizar los documentos ante cualquier cambio en la base de datos.

Es importante que la documentación del código asociada al código fuente (que puede incluir archivos README y documentación de la interfaz de programación de aplicaciones ( API )) sea completa, pero no tan extensa que resulte excesivamente laboriosa o difícil de mantener. Los desarrolladores de API suelen encontrar diversas guías de documentación, tanto prácticas como generales, específicas para la aplicación o el producto de software que están documentando . Esta documentación puede ser utilizada por desarrolladores, evaluadores y usuarios finales. Actualmente, se observan numerosas aplicaciones de alta gama en los sectores de energía, transporte, redes, aeroespacial, seguridad, automatización industrial y otros ámbitos. La documentación técnica se ha vuelto fundamental en estas organizaciones, ya que el nivel de información, tanto básico como avanzado, puede variar con el tiempo debido a los cambios en la arquitectura. Existen pruebas de que una buena documentación del código reduce los costes de mantenimiento del software. ^{[ 1 ]}

Los documentos de código suelen estar organizados a modo de guía de referencia , lo que permite al programador consultar rápidamente cualquier función o clase.

A diferencia de los documentos de código, los documentos de usuario simplemente describen cómo se utiliza un programa.

En el caso de una biblioteca de software , los documentos de código y los documentos de usuario podrían, en algunos casos, ser prácticamente equivalentes y merecer la pena combinarlos, pero para una aplicación general esto no suele ser así.

Normalmente, la documentación del usuario describe cada función del programa y ayuda al usuario a comprenderlas. Es fundamental que la documentación sea clara y esté actualizada. No es necesario que siga un formato específico, pero sí es importante que cuente con un índice completo . La coherencia y la simplicidad también son esenciales. La documentación del usuario se considera un contrato que especifica el funcionamiento del software. Los redactores de API son expertos en la redacción de buena documentación, ya que conocen a fondo la arquitectura del software y las técnicas de programación utilizadas. Véase también redacción técnica .

La documentación del usuario se puede producir en una variedad de formatos en línea e impresos. ^{[ 2 ]} Sin embargo, la documentación del usuario se puede organizar de tres maneras principales:

1. Tutorial : Se considera que un enfoque tutorial es el más útil para un nuevo usuario, en el que se le guía a través de cada paso para completar las tareas asignadas. ^{[ 3 ]}
2. Enfoque temático : Un enfoque temático , donde los capítulos o secciones se centran en un área de interés específica, resulta más útil para un usuario intermedio. Algunos autores prefieren transmitir ideas a través de un artículo basado en el conocimiento para facilitar la comprensión de las necesidades del usuario. Este enfoque suele ser practicado por industrias dinámicas, como la de las tecnologías de la información . ^{[ 4 ]}
3. Listado o referencia : El último tipo de principio de organización consiste en enumerar los comandos o tareas alfabéticamente o agruparlos lógicamente, a menudo mediante índices con referencias cruzadas. Este último método resulta más útil para usuarios avanzados que saben exactamente qué tipo de información buscan.

Una queja común entre los usuarios respecto a la documentación del software es que solo se adoptó uno de estos tres enfoques, prácticamente excluyendo los otros dos. Es frecuente que la documentación proporcionada para ordenadores personales se limite a la ayuda en línea , que solo ofrece información de referencia sobre comandos o elementos del menú. La tarea de guiar a los nuevos usuarios o ayudar a los más experimentados a sacar el máximo provecho de un programa recae en las editoriales privadas, que a menudo reciben una importante ayuda del desarrollador del software.

Para muchas aplicaciones es necesario contar con materiales promocionales que animen a los observadores ocasionales a dedicar más tiempo a conocer el producto. Este tipo de documentación tiene tres propósitos:

1. El objetivo es entusiasmar al usuario potencial con el producto e inculcarle el deseo de involucrarse más con él.
2. Para informarles sobre qué hace exactamente el producto, de modo que sus expectativas se ajusten a lo que van a recibir.
3. Explicar la posición de este producto con respecto a otras alternativas.

Docs as Code es un sistema de documentación que la trata con el mismo rigor y los mismos procesos que el código de software. Esto incluye:

1. Control de versiones : uso de sistemas como Git para realizar un seguimiento de los cambios y gestionar las versiones.
2. Integración continua : automatización del proceso de generación y actualización de la documentación.
3. Colaboración : permitir que varios colaboradores trabajen en la documentación simultáneamente, como en el desarrollo de código.