Tengo la tarea de liderar el esfuerzo de documentación para un producto de software existente, completamente indocumentado, ¿qué recursos hay para ayudarme?

Soy desarrollador de software en una empresa de tecnología. Me encargaron liderar el esfuerzo de documentación del producto en el que trabajo. El objetivo es producir documentación interna para el desarrollador, y el proyecto se extiende al lado comercial, donde cubre la documentación de requisitos.

Este proyecto es desafiante. Específicamente, estoy tratando con un producto que: - ha existido durante mucho tiempo, al menos 6 años. - no tiene ningún tipo de documentación que no sea algunas piezas pequeñas y obsoletas aquí y allá. - tiene comentarios en el código, pero son técnicos y no transmiten ningún comportamiento general (incluso en el aspecto técnico). - como consecuencia de tener poca o ninguna documentación, a menudo es innecesariamente complejo bajo las cubiertas

Además, no se nos ha dado mucho tiempo para trabajar en este proyecto.

No tengo ninguna documentación formal o antecedentes de escritura, capacitación o experiencia. He mostrado cierta habilidad en la escritura / comunicación en la oficina, por lo que me asignaron a este proyecto.

Por favor comparta su consejo o recomendación de recursos para ayudarme a preparar y manejar este proyecto. Estoy buscando referencias a libros / sitios web / foros / lo que sea, para ayudarme a diseñar un plan con hitos, aprender sobre las mejores prácticas, delegación de tareas, plantillas, aceptación, etc.

Espero específicamente recursos dirigidos o dando una mención especial de la introducción de buena documentación a proyectos existentes, indocumentados .

Por lo general, uso una wiki y solo hago spam a medida que avanzo en el proceso de descubrimiento. Wiki porque obtienes búsqueda e historial, así como funciones de edición en equipo. La herramienta exacta es menos importante que tener una búsqueda funcional y hacer que todos la usen. Al principio, espere que sea muy difícil, pero aliente a las personas a tomar esas notas aproximadas a medida que avanzan porque eso es todo lo que obtendrá al principio.

Algunas cosas que ayudan mucho:

• tener un editor Usted, probablemente, al principio, pero si tiene el presupuesto, hágalo parte del trabajo de alguien. Elija a alguien que sea bueno con el lenguaje en lugar de ser un genio técnico. Edite para obtener claridad en lugar de perfección: desea alentar a las personas a escribir buenas entradas, pero al principio deberá guiarlas.
• use diagramas, pero exija que se use una herramienta relevante, se genere la imagen y se adjunte el archivo fuente a la página. De esa forma, las personas pueden editar su imagen utilizando la herramienta adecuada en lugar de MS-Paint. Pocas cosas apestan más que un diagrama realmente bueno construido en Visio para el que ya no tienes el documento fuente, solo un PNG extraído de él.
• Fomentar la reorganización y la edición. Incluso si no es genial al principio, necesita personas para recopilar información y corregir errores. Mentor personas para hacer esto bien.
• mencione esto en sus reuniones de equipo semanales. Obtenga la lista de ediciones recientes antes de entrar y elogie a las personas que han agregado algo útil, luego pregunte por qué aquellos que no lo han hecho, no lo han hecho.

Comencé con una imagen de máquina virtual MediaWiki en el pasado porque es muy rápido y fácil de comenzar, por lo que las personas que dicen "es demasiado difícil" no obtienen ninguna tracción inicial.

Si su idioma / entorno lo admite utilizando herramientas de tipo JavaDoc / NDoc para extraer los comentarios a medida que los agrega, es un buen enfoque de bajo nivel. Pero eso es menos útil que la documentación de alto nivel, y aunque las herramientas son un tipo de soporte para agregar cosas de alto nivel, crearlo de la nada usando solo esas herramientas es innecesariamente laborioso.

Si está documentando el código en sí y no está haciendo la documentación del usuario final, Doxygen es una gran herramienta si sus lenguajes de desarrollo son compatibles. Lo ejecuta sobre su código y crea un sitio web que enumera todas sus funciones, clases, etc. Luego puede agregar comentarios de código con formato especial para agrupar cosas y agregar más detalles. Es una excelente manera de documentar incrementalmente una base de código.

Con respecto a la documentación del código, si Doxygen no satisface sus necesidades, hay muchas herramientas alternativas disponibles. Wikipedia tiene una lista de casi 50 herramientas de este tipo e incluye detalles de su funcionalidad y soporte de idiomas.

Descargo de responsabilidad: estoy asociado con una de las herramientas, Imagix 4D .

Estas son solo algunas ideas que pueden ser útiles en algún nivel:

¿Ha pensado qué forma tomará esta documentación al final? Será un documento de Word, un DVD, un sitio con una serie de páginas que desglosan la aplicación, una herramienta de blog que simplemente recita los detalles de la aplicación a medida que uno se sumerge ¿usando algún sistema de administración de documentos estándar como Share Point u otra cosa? Obteniendo resultados sería un ejemplo de un libro en línea que es una serie de páginas, por ejemplo.

¿Qué tipo de control de versión y proceso de edición desea que tome esta documentación? Es otro tema que vale la pena considerar antes de adentrarse demasiado en esto. ¿Cómo desea manejar las actualizaciones y los cambios?

Es probable que la retroalimentación sea otra dimensión interesante sobre esto, ya que sea lo que sea que crees habrá más que unas pocas críticas y qué tan bien se priorizan y estrangulan esos cambios es otra pregunta que consideraría antes de sacar esa primera versión.

¡Buena suerte!

La construcción de documentación, como la construcción de todos los demás tipos de software, es un proceso intrínsecamente complejo.

Es por eso que los desarrolladores de software inventaron los métodos ágiles.

La documentación es solo software sin un compilador. Los mismos métodos para proyectos de software se aplican a proyectos de documentación. Precisamente el mismo razonamiento.

Cuando escribe software comienza con casos de uso (o historias de usuarios). La documentación no es diferente.

Prioriza los casos de uso con un presupuesto aproximado.

Tienes sprints

Tienes lanzamientos.

Usted asegura la calidad - prueba - revisión - corrección y relanzamiento.

Es exactamente como construir software.

¿Quiénes son sus usuarios? ¿Qué problemas tienen? ¿Cómo resolverá el documento su problema? Priorizar Pique. Eventualmente, liberarás.