Documentación del software

La documentación del software es un texto escrito o una ilustración que acompaña al software de la computadora o está incrustado en el código fuente. La documentación explica cómo funciona el software o cómo usarlo, y puede significar diferentes cosas para las personas en diferentes roles.

La documentación es una parte importante de la ingeniería de software. Los tipos de documentación incluyen:

• Requisitos – Declaraciones que identifican atributos, capacidades, características o cualidades de un sistema. Esta es la base para lo que será o se ha implementado.
• Arquitectura/Diseño – Resumen del software. Incluye relaciones con un entorno y principios de construcción que se utilizarán en el diseño de componentes de software.
• Técnica – Documentación de código, algoritmos, interfaces y APIs.
• Usuario final – Manuales para el usuario final, administradores del sistema y personal de soporte.
• Marketing – Cómo comercializar el producto y el análisis de la demanda del mercado.

Documentación de requisitos

La documentación de requisitos es la descripción de lo que hace o debe hacer un software en particular. Se utiliza a lo largo del desarrollo para comunicar cómo funciona el software o cómo se pretende que funcione. También se utiliza como acuerdo o como base para un acuerdo sobre lo que hará el software. Los requisitos son producidos y consumidos por todos los involucrados en la producción de software, incluidos: usuarios finales, clientes, gerentes de proyectos, ventas, marketing, arquitectos de software, ingenieros de usabilidad, diseñadores de interacción, desarrolladores y evaluadores.

Los requisitos vienen en una variedad de estilos, notaciones y formalidad. Los requisitos pueden ser similares a objetivos (p. ej., entorno de trabajo distribuido), cercanos al diseño (p. ej., las compilaciones se pueden iniciar haciendo clic con el botón derecho en un archivo de configuración y seleccionando la 'compilación'). 39; función), y cualquier cosa intermedia. Se pueden especificar como enunciados en lenguaje natural, como figuras dibujadas, como fórmulas matemáticas detalladas y como una combinación de todos ellos.

La variación y complejidad de la documentación de requisitos la convierte en un desafío probado. Los requisitos pueden ser implícitos y difíciles de descubrir. Es difícil saber exactamente cuánto y qué tipo de documentación se necesita y cuánto se puede dejar para la documentación de arquitectura y diseño, y es difícil saber cómo documentar los requisitos considerando la variedad de personas que leerán y utilizarán la documentación.. Por lo tanto, la documentación de requisitos a menudo está incompleta (o no existe). Sin la documentación de requisitos adecuada, los cambios de software se vuelven más difíciles y, por lo tanto, más propensos a errores (disminución de la calidad del software) y más lentos (costosos).

La necesidad de documentación de requisitos suele estar relacionada con la complejidad del producto, el impacto del producto y la expectativa de vida del software. Si el software es muy complejo o fue desarrollado por muchas personas (por ejemplo, software para teléfonos móviles), los requisitos pueden ayudar a comunicar mejor lo que se debe lograr. 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 viva solo uno o dos meses (por ejemplo, aplicaciones de teléfonos móviles muy pequeñas desarrolladas específicamente para una determinada campaña), es posible que se necesite muy poca documentación de requisitos. Si el software es una primera versión que luego se desarrolla, la documentación de requisitos es muy útil al administrar el cambio del software y verificar que nada se haya roto en el software cuando se modificó.

Tradicionalmente, los requisitos se especifican en los documentos de requisitos (por ejemplo, utilizando aplicaciones de procesamiento de textos y aplicaciones de hojas de cálculo). Para gestionar la mayor complejidad y la naturaleza cambiante de la documentación de requisitos (y la documentación de software en general), se recomiendan los sistemas centrados en bases de datos y las herramientas de gestión de requisitos para propósitos especiales.

En el desarrollo de software Agile, los requisitos a menudo se expresan como historias de usuario con los criterios de aceptación que los acompañan.

Documentación de diseño de arquitectura

La documentación de la arquitectura (también conocida como descripción de la arquitectura del software) es un tipo especial de documento de diseño. En cierto modo, los documentos de arquitectura son la tercera derivada del código (el documento de diseño es la segunda derivada y los documentos de código son la primera). Muy poco en los documentos de arquitectura es específico del código en sí. Estos documentos no describen cómo programar una rutina en particular, o incluso por qué esa rutina en particular existe en la forma en que lo hace, sino que simplemente establece los requisitos generales que motivarían la existencia de dicha rutina. Un buen documento de arquitectura es breve en detalles pero abundante en explicaciones. Puede sugerir enfoques para el diseño de nivel inferior, pero deja los estudios comerciales de exploración reales para otros documentos.

Otro tipo de documento de diseño es el documento de comparación o estudio comercial. Esto a menudo tomaría la forma de un documento técnico. Se enfoca en un aspecto específico del sistema y sugiere enfoques alternativos. Podría ser a nivel de interfaz de usuario, código, diseño o incluso arquitectura. Esbozará cuál es la situación, describirá una o más alternativas y enumerará los pros y los contras de cada una. Un buen documento de estudio comercial tiene una gran cantidad de investigación, expresa su idea con claridad (sin depender demasiado de una jerga obtusa para deslumbrar al lector) y, lo que es más importante, es imparcial. Debe explicar honesta y claramente los costos de cualquier solución que ofrezca como la mejor. El objetivo de un estudio comercial es idear la mejor solución, en lugar de impulsar un punto de vista particular. Es perfectamente aceptable no establecer ninguna conclusión o concluir que ninguna de las alternativas es lo suficientemente mejor que la línea de base para justificar un cambio. Debe abordarse como un esfuerzo científico, no como una técnica de marketing.

Una parte muy importante del documento de diseño en el desarrollo de software empresarial es el Documento de diseño de la base de datos (DDD). 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. El propósito de prepararlo es crear una fuente común para ser utilizada por todos los jugadores dentro de la escena. 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:

• Entidad - Plan de Relación (reforzado o no), incluyendo la siguiente información y sus definiciones claras:
  • Conjuntos de Entidades y sus atributos
  • Relaciones y sus atributos
  • Candidato claves para cada entidad establecido
  • Attribute and Tuple based constraints
• Relational Schema, including following information:
  • Tablas, Atributos y sus propiedades
  • Vistas
  • Limitaciones como llaves primarias, llaves extranjeras,
  • Cardinality of referential constraints
  • Política de Cascación para limitaciones de referencia
  • Principales claves

Es muy importante incluir toda la información que usarán todos los actores en la escena. También es muy importante actualizar los documentos ya que cualquier cambio ocurre también en la base de datos.

Documentación técnica

Es importante que los documentos de código asociados con el código fuente (que pueden incluir archivos LÉAME y documentación de la API) sean completos, pero no tan detallados que consuman demasiado tiempo o dificulten su mantenimiento. Por lo general, se encuentran varias guías de documentación de procedimientos e información general específicas para la aplicación de software o el producto de software que están documentando los escritores de API. Esta documentación puede ser utilizada por desarrolladores, evaluadores y también por usuarios finales. Hoy en día, se ven muchas aplicaciones de alto nivel en los campos de la potencia, la energía, el transporte, las redes, la industria aeroespacial, la seguridad, la automatización de la industria y una variedad de otros dominios. La documentación técnica se ha vuelto importante dentro de tales organizaciones, ya que el nivel básico y avanzado de información puede cambiar durante un período de tiempo con cambios en la arquitectura.

Los documentos de código a menudo se organizan en un estilo de guía de referencia, lo que permite a un programador buscar rápidamente una función o clase arbitraria.

Documentación técnica incrustada en el código fuente

A menudo, se pueden usar herramientas como Doxygen, NDoc, Visual Expert, Javadoc, JSDoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText o Universal Report para generar automáticamente los documentos de código, es decir, extraen los comentarios. y contratos de software, cuando estén disponibles, a partir del código fuente y crear manuales de referencia en forma de archivos de texto o HTML.

La idea de la documentación autogenerada es atractiva para los programadores por varias razones. Por ejemplo, debido a que se extrae del propio código fuente (por ejemplo, a través de comentarios), el programador puede escribirlo refiriéndose al código y usar las mismas herramientas que utilizó para crear el código fuente para hacer la documentación. Esto hace que sea mucho más fácil mantener la documentación actualizada.

Por supuesto, una desventaja es que solo los programadores pueden editar este tipo de documentación, y depende de ellos actualizar la salida (por ejemplo, ejecutando un trabajo cron para actualizar los documentos todas las noches). Algunos caracterizarían esto como un pro en lugar de una estafa.

Programación alfabetizada

El respetado científico informático Donald Knuth ha señalado que la documentación puede ser un proceso secundario muy difícil y ha defendido la programación alfabetizada, escrita al mismo tiempo y en el mismo lugar que el código fuente y extraída por medios automáticos. Los lenguajes de programación Haskell y CoffeeScript tienen soporte incorporado para una forma simple de programación alfabetizada, pero este soporte no se usa mucho.

Programación aclaratoria

La Programación Elucidativa es el resultado de aplicaciones prácticas de la Programación Alfabetizada en contextos reales de programación. El paradigma Elucidative propone que el código fuente y la documentación se almacenen por separado.

A menudo, los desarrolladores de software necesitan poder crear y acceder a información que no formará parte del propio archivo de origen. Estas anotaciones suelen formar parte de varias actividades de desarrollo de software, como recorridos de código y portabilidad, donde el código fuente de terceros se analiza de manera funcional. Por lo tanto, las anotaciones pueden ayudar al desarrollador durante cualquier etapa del desarrollo de software en la que un sistema de documentación formal obstaculizaría el progreso.

Documentación del usuario

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 efectivamente equivalentes y vale la pena unirlos, pero para una aplicación general esto no suele ser cierto.

Normalmente, la documentación del usuario describe cada función del programa y ayuda al usuario a realizar estas funciones. Es muy importante que los documentos de usuario no sean confusos y que estén actualizados. Los documentos de usuario no necesitan estar organizados de ninguna manera en particular, pero es muy importante que tengan un índice completo. La consistencia y la simplicidad también son muy valiosas. Se considera que la documentación del usuario constituye un contrato que especifica lo que hará el software. Los escritores de API están muy bien preparados para escribir buenos documentos de usuario, ya que conocen bien 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 impresos y en línea. Sin embargo, hay tres formas generales en las que se puede organizar la documentación del usuario.

1. Tutorial: Un enfoque tutorial se considera el más útil para un nuevo usuario, en el que se guía a través de cada paso de realizar tareas particulares.
2. Tema: Un enfoque temático, donde capítulos o secciones se concentran en un área de interés particular, es de mayor uso general para un usuario intermedio. Algunos autores prefieren transmitir sus ideas a través de un artículo basado en el conocimiento para facilitar las necesidades del usuario. Este enfoque suele ser practicado por una industria dinámica, como la tecnología de la información.
3. Lista o Referencia: El tipo final de principio de organización es uno en el que comandos o tareas se enumeran simplemente alfabéticamente o lógicamente agrupados, a menudo a través de índices de referencia cruzada. Este último enfoque es de mayor uso para los usuarios avanzados que saben exactamente qué tipo de información están buscando.

Una queja común entre los usuarios con respecto a la documentación del software es que solo se tomó uno de estos tres enfoques hasta casi excluir a los otros dos. Es común limitar la documentación de software proporcionada para computadoras personales a la ayuda en línea que brinda solo información de referencia sobre comandos o elementos de menú. El trabajo de dar tutoría a los nuevos usuarios o ayudar a los usuarios más experimentados a sacar el máximo provecho de un programa se deja en manos de los editores privados, a quienes a menudo el desarrollador del software les brinda una asistencia significativa.

Componer la documentación del usuario

Al igual que otras formas de documentación técnica, una buena documentación de usuario se beneficia de un proceso de desarrollo organizado. En el caso de la documentación del usuario, el proceso, tal como ocurre comúnmente en la industria, consta de cinco pasos:

1. Análisis de usuarios, fase básica de investigación del proceso.
2. Planificación o fase de documentación real.
3. Proyecto de examen, fase autoexplicativa en la que se solicita información sobre el proyecto que figura en el paso anterior.
4. Pruebas de usabilidad, por lo que la usabilidad del documento se prueba empíricamente.
5. Edición, el paso final en el que se utiliza la información recogida en los pasos tres y cuatro para producir el borrador final.

Controversia sobre documentación y desarrollo ágil

"La resistencia a la documentación entre los desarrolladores es bien conocida y no necesita énfasis." Esta situación es particularmente frecuente en el desarrollo ágil de software porque estas metodologías intentan evitar cualquier actividad innecesaria que no aporte valor directamente. Específicamente, el Manifiesto Ágil aboga por valorar el "software funcional sobre la documentación completa", lo que podría interpretarse cínicamente como "Queremos pasar todo nuestro tiempo codificando. Recuerde, los verdaderos programadores no escriben documentación."

Una encuesta entre expertos en ingeniería de software reveló, sin embargo, que la documentación no se considera innecesaria en el desarrollo ágil. Sin embargo, se reconoce que existen problemas de motivación en el desarrollo y que pueden ser necesarios métodos de documentación adaptados al desarrollo ágil (por ejemplo, a través de sistemas de reputación y gamificación).

Documentación de marketing

Para muchas aplicaciones, es necesario contar con algunos materiales promocionales para alentar a los observadores ocasionales a pasar más tiempo aprendiendo sobre el producto. Esta forma de documentación tiene tres propósitos:

1. Excitar al usuario potencial sobre el producto e inculcar en ellos un deseo de involucrarse más con él.
2. Para informarles sobre lo que hace exactamente el producto, para que sus expectativas estén en consonancia con lo que recibirán.
3. Explicar la posición de este producto con respecto a otras alternativas.