¿Qué comprende exactamente 'Documentación'?

Cuando decimos 'documentación' para un producto de software, ¿qué incluye eso y qué no debería incluir?

Por ejemplo, una pregunta reciente preguntó si los comentarios se consideran documentación.

Pero también hay muchas otras áreas para las que esta es una pregunta válida, algunas más obvias que otras:

• Manuales (obviamente)
• ¿Notas de lanzamiento?
• Tutoriales
• Comentarios
• ¿Cualquier otro?

Dónde está dibujada la línea. Por ejemplo, si 'tutorial' es documentación, es documentación de 'video tutorial', o es algo más?

En general, algo en el software no se 'hace' hasta que se implementa, prueba y documenta. De ahí esta pregunta, ¿qué cosas deberíamos considerar como parte de la documentación para considerar algo 'hecho'?

_{La pregunta se inspira en los comentarios recientes de los clientes en nuestra conferencia que indica que nuestro documento necesitaba más 'muestras', que anteriormente no habíamos sido tan buenos en considerar como deberíamos haber sido.}

_{Audiencia: Desarrolladores de software que utilizan nuestra (s) base (s) de datos, lenguajes de programación y herramientas asociadas (como clientes de administración de dicho DB)}

El objetivo de la documentación es describir y explicar el producto de software, para que pueda definir la documentación como el conjunto de artefactos que contribuyen a esa descripción o explicación. Probablemente no consideraría acciones relacionadas como parte de la documentación: por ejemplo, un curso de capacitación de una semana no es documentación, pero los materiales del curso sí lo son; un chat de pizarra blanca de cinco minutos no es documentación, pero sí una imagen de la pizarra.

Teniendo en cuenta el objetivo (explicando el software), la documentación finaliza cuando el cliente está satisfecho con la explicación : así como el software finaliza cuando el cliente está satisfecho con el software. Tenga en cuenta que el cliente para la documentación no siempre es el mismo que el cliente que paga por el software: el personal de soporte, los probadores, los vendedores y otros necesitarán una comprensión de lo que hace el software y cómo funciona.

Esto ayuda a comprender dónde se encuentra su límite para lo que debe incluirse en la documentación. Usar "lector" como una forma abreviada conveniente, aunque aceptamos que se pueden incluir videos o audio: cualquier cosa que ayude al lector a obtener la información que necesita sobre el software es documentación que puede usar, todo lo demás no lo es. Si su cliente necesita recorridos detallados de todos sus casos de uso, entonces eso debe ser parte de la documentación. Sus desarrolladores probablemente necesiten código fuente, información sobre su repositorio de control de versiones e instrucciones de compilación: esa es documentación para ellos, pero como se describió anteriormente, no sería parte de la documentación del cliente.

Creo que le quitó la parte equivocada de su conversación en una conferencia. Las metodologías modernas de desarrollo de software recomiendan que el equipo de desarrollo trabaje estrechamente con sus clientes (o con un propietario del producto que actúe como representante del cliente). Para todo el trabajo entregado, la definición de "hecho" es algo que se negocia entre el equipo y su cliente y se hace de forma recurrente a medida que se desarrolla el software.

El problema con el que se topó es que tenía una desconexión entre lo que suponía que el cliente necesitaba y lo que esperaban que entregara, por lo que al final recibió la sorpresa de "oye dónde están todas las muestras".

En cuanto a la documentación ... bueno, es casi todo lo que enumeraste y quizás algunas cosas más que no hiciste. Pero nadie puede decirle cuánta documentación necesita su proyecto. Cada proyecto es diferente y depende de su equipo, el propietario de su producto y sus clientes determinar el nivel y el tipo de documentación que se requiere para su proyecto.

Algunos factores que entrarían en juego:

• ¿Está desarrollando el software v1.0 y se están trasladando a otros proyectos o este es un proyecto en curso a largo plazo? Los comentarios / documentos de diseño se vuelven mucho más importantes en este último caso. Por otro lado, si su cliente es una tienda de donas de mamá y papá y está escribiendo un sitio web para ellos que nunca verá ... bueno, supongo que la documentación del código es buena pero no tan importante.
• ¿Está desarrollando un juego o software móvil que controla el monitor de frecuencia cardíaca en un hospital? ¿Adivina cuál tendrá la definición de "hecho" que tiene mucha más documentación?
• ¿Son sus clientes usuarios finales típicos o son otros desarrolladores? ¿Tiene una API / SDK que está exponiendo?
• ¿Cuál es el nivel de experiencia de sus clientes? Esto afecta la elección del video tutorial versus el material escrito versus algún tipo de aplicación de tutorial interactivo
• ¿A sus clientes les importa lo que cambió de una versión a otra? Algunos lo hacen. La mayoría no lo hace. Para pocos, es la ley (o cercana a eso) preocuparse.

La documentación es material destinado a ser leído sin modificarlo.

Creo que no puede equivocarse con la definición basada en el propósito ... pero solo si define el propósito correctamente.

• ^{Definir correctamente el propósito de la documentación no es del todo simple. La distinción directa (ingenua si lo desea) que naturalmente viene a la mente es que la documentación es todo lo que está destinado a la lectura , mientras que, en comparación, el código es cualquier cosa destinada a la ejecución de la computadora . Suena bien en la superficie, ¿no? pero realmente resulta bastante feo una vez que profundizas.
   
  La cuestión es que un buen código tiene en cuenta los problemas de legibilidad, junto con la corrección de la ejecución; esto hace que la distinción de "legibilidad" sea bastante inútil para definir la documentación.
   
  Las mismas muestras que mencionaste muestran lo que le pasa. Los clientes generalmente esperan que estos estén claramente escritos yejecutar correctamente Comprometer la legibilidad o la corrección puede generar una cascada de quejas de los clientes. La distinción ingenua no ayuda a determinar si las muestras son código o documentación.
   
  El uso de la distinción ingenua se volverá aún más complicado si imagina trabajar con código abierto . Lo descargas, lo compilas y lo ejecutas, no lo lees, es solo el código, ¿verdad? Espera, las cosas de alguna manera salieron mal y llegaste al código para leer lo que está sucediendo allí ... oye, no lees ejecutar, ¿es esta documentación ahora? Y, finalmente, encuentra un error en la fuente y lo repara: ahora este es realmente el código, no es algo que normalmente se llama documentación, sin importar cuán cuidadosamente lo lea para corregirlo.}

Para las 'muestras' que va a proporcionar, la distinción lectura-no-modificación podría resultar bastante importante.

Mire, si alguna muestra falla cuando se ejecuta sin cambios, en el entorno de referencia documentado, es su error - error en su documentación, uno que debe aceptar y corregir, está bien.

Ahora, si hay un problema con la muestra o el entorno modificados, ya no es culpa suya, es decir, no hay ningún error en la documentación, ya que los documentos no están destinados a modificación. Cualquier ayuda que brinde a los usuarios en ese caso, se incluiría en la categoría de soporte, no en una corrección de errores.

Cualquier cosa que responda a una pregunta de "¿cómo ...?" Es documentación.

Para los desarrolladores, eso significa especificaciones de requisitos ("cómo sé qué escribir"), documentos de diseño ("cómo abordo mis requisitos"), matrices de trazabilidad ("cómo sé que mi diseño cumple con todos mis requisitos"), planes de prueba ( "¿cómo sé que mis obras de código"), las pruebas unitarias ( "¿cómo sé que he safisfied requisito X"), comentarios en línea ( "¿Cómo puedo hacer que la próxima pobres schlub entiende por qué escribí este forma "), instrucciones de implementación (" cómo empaqueto este producto para la instalación "), etc.

Para los usuarios, que los manuales de medios de usuario ( "¿Cómo utilizar el software"), tutoriales ( "cómo se utiliza esta característica específica"), notas de la versión ( "¿cómo sé qué errores han sido corregidos / nuevos insectos características han sido añadido "), etc.