La documentación de software es un texto escrito o una ilustración que acompaña al software de la computadora o está incorporada en el código fuente. La documentación explica cómo funciona el software o cómo usarlo, y puede tener distintos significados para personas que desempeñan distintos roles.
La documentación es una parte importante de la ingeniería de software. Los tipos de documentación incluyen:
La documentación de requisitos es la descripción de lo que hace o debería hacer un software en particular. Se utiliza durante todo el desarrollo para comunicar cómo funciona el software o cómo se pretende que funcione. También se utiliza como un 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 se presentan en una variedad de estilos, notaciones y formalidades. Los requisitos pueden ser similares a objetivos (por ejemplo, entorno de trabajo distribuido ), cercanos al diseño (por ejemplo, las compilaciones se pueden iniciar haciendo clic derecho en un archivo de configuración y seleccionando la función 'compilar' ) y cualquier cosa intermedia. Se pueden especificar como declaraciones en lenguaje natural , como figuras dibujadas, como fórmulas matemáticas detalladas o como una combinación de todas ellas.
La variedad 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 saber exactamente cuánta 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 usarán la documentación. Por lo tanto, la documentación de requisitos a menudo es incompleta (o inexistente). Sin una 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 requieren más tiempo (costo).
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 ha sido desarrollado por muchas personas (por ejemplo, software de telefonía móvil), 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 documentación de requisitos más formal. Si se espera que el software esté disponible solo durante un mes o dos (por ejemplo, aplicaciones de telefonía móvil 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 se desarrollará posteriormente, la documentación de requisitos es muy útil para gestionar el cambio del software y verificar que no se haya roto nada en el software cuando se modifique.
Tradicionalmente, los requisitos se especifican en documentos de requisitos (por ejemplo, mediante aplicaciones de procesamiento de textos y hojas de cálculo). Para gestionar la creciente complejidad y la naturaleza cambiante de la documentación de requisitos (y la documentación de software en general), se recomiendan sistemas centrados en bases de datos y herramientas de gestión de requisitos para fines específicos.
En el desarrollo de software ágil, los requisitos suelen expresarse como historias de usuario acompañadas de criterios de aceptación. Las historias de usuario suelen ser parte de una característica o una epopeya, que es una funcionalidad más amplia o un conjunto de funcionalidades relacionadas que ofrecen un valor específico al usuario en función de los requisitos comerciales.
La documentación de 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 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 establecen 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 de exploración comercial reales para otros documentos.
Otro tipo de documento de diseño es el documento de comparación o estudio comercial. Este suele adoptar la forma de un informe técnico . Se centra en un aspecto específico del sistema y sugiere enfoques alternativos. Puede 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 mucho de investigación, expresa su idea con claridad (sin depender demasiado de una jerga obtusa para deslumbrar al lector) y, lo más importante, es imparcial. Debe explicar de manera honesta y clara los costos de la mejor solución que ofrece. 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 afirmar 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 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 que la utilicen todos los participantes dentro de la escena. Los usuarios potenciales son:
Cuando se habla de sistemas de bases de datos relacionales , el documento debe incluir las siguientes partes:
Es muy importante incluir toda la información que utilizarán todos los actores de la escena. También es muy importante actualizar los documentos a medida que se produzcan cambios en la base de datos.
Es importante que los documentos de código asociados con el código fuente (que pueden incluir archivos README y documentación de API ) sean completos, pero no tan detallados que resulten demasiado lentos o difíciles de mantener. Es común encontrar varias guías de documentación de instrucciones y descripción general específicas para la aplicación de software o el producto de software que los escritores de API están documentando . Esta documentación puede ser utilizada por desarrolladores, evaluadores y también usuarios finales. Hoy en día, se ven muchas aplicaciones de alta gama en los campos de la energía, el transporte, las redes, la industria aeroespacial, la seguridad, la automatización industrial y una variedad de otros dominios. La documentación técnica se ha vuelto importante dentro de dichas organizaciones, ya que el nivel básico y avanzado de información puede cambiar a lo largo del tiempo con los cambios de arquitectura. Existe evidencia de que la existencia de una buena documentación de código en realidad reduce los costos de mantenimiento del software. [1]
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.
A menudo, se pueden utilizar 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 los contratos de software , cuando están disponibles, del código fuente y crean manuales de referencia en formatos como archivos de texto o HTML .
La idea de generar documentación automáticamente resulta atractiva para los programadores por varias razones. Por ejemplo, dado que se extrae del propio código fuente (por ejemplo, a través de comentarios ), el programador puede escribirla haciendo referencia al código y utilizar las mismas herramientas que utilizó para crear el código fuente para realizar la documentación. Esto hace que sea mucho más fácil mantener la documentación actualizada.
Una posible desventaja es que solo los programadores pueden editar este tipo de documentación, y depende de ellos actualizar la salida (por ejemplo, ejecutando una tarea cron para actualizar los documentos todas las noches). Algunos caracterizarían esto como una ventaja en lugar de una desventaja.
El respetado científico informático Donald Knuth ha señalado que la documentación puede ser un proceso muy difícil y que se lleva a cabo a posteriori, y ha defendido la programación alfabetizada , escrita en el mismo momento y lugar que el código fuente y extraída por medios automáticos. Los lenguajes de programación Haskell y CoffeeScript tienen soporte integrado para una forma sencilla de programación alfabetizada, pero este soporte no se utiliza ampliamente.
La Programación Elucidativa es el resultado de aplicaciones prácticas de la Programación Literaria en contextos de programación reales. El paradigma Elucidativo 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 va a formar parte del archivo fuente en sí. Estas anotaciones suelen formar parte de varias actividades de desarrollo de software, como recorridos de código y portabilidad, en las que se analiza el código fuente de terceros de forma 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.
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 valer la pena combinarlos, pero para una aplicación general esto no suele ser así.
Por lo general, la documentación del usuario describe cada característica del programa y ayuda al usuario a comprenderlas. Es muy importante que los documentos del usuario no sean confusos y que estén actualizados. Los documentos del usuario no necesitan estar organizados de ninguna manera en particular, pero es muy importante que tengan un índice completo . La coherencia y la simplicidad también son muy valiosas. La documentación del usuario se considera un contrato que especifica lo que hará el software. Los escritores de API son muy competentes en la redacción de buenos documentos de usuario, ya que conocen bien la arquitectura del software y las técnicas de programación utilizadas. Consulte 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, hay tres formas generales en las que se puede organizar la documentación del usuario.
Una queja habitual entre los usuarios con respecto a la documentación de software es que sólo se adoptó uno de estos tres enfoques, con casi exclusión de los otros dos. Es habitual limitar la documentación de software proporcionada para ordenadores personales a la ayuda en línea que sólo ofrece información de referencia sobre comandos o elementos de menú. La tarea de orientar a los nuevos usuarios o ayudar a los usuarios más experimentados a sacar el máximo partido de un programa se deja en manos de los editores privados, a quienes a menudo el desarrollador del software les proporciona una ayuda importante.
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 de usuario, el proceso tal como se da comúnmente en la industria consta de cinco pasos: [5]
Para muchas aplicaciones es necesario contar con algún material promocional para alentar a los observadores ocasionales a dedicar más tiempo a aprender sobre el producto. Esta forma de documentación tiene tres propósitos:
“La resistencia a la documentación entre los desarrolladores es bien conocida y no necesita enfatizarse.” [10] Esta situación es particularmente frecuente en el desarrollo de software ágil porque estas metodologías intentan evitar cualquier actividad innecesaria que no aporte valor directamente. En concreto, el Manifiesto Ágil aboga por valorar “el software funcional por encima de la documentación exhaustiva”, lo que podría interpretarse cínicamente como “Queremos pasar todo nuestro tiempo codificando. Recuerde, los verdaderos programadores no escriben documentación.” [11]
Sin embargo, una encuesta realizada entre expertos en ingeniería de software reveló que la documentación no se considera en absoluto 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 ). [12] [13]
Docs as Code es un enfoque de la documentación que la trata con el mismo rigor y los mismos procesos que el código de software. Esto incluye: