Determinar la cantidad correcta de documentación

Donde trabajo actualmente es el enfoque general:

evitar la documentación tanto como sea posible

Solo documente si un equipo diferente lo necesitará

solo para aclarar, no me refiero a la documentación del código; esto lo hacemos, me refiero a toda la documentación que rodea el proceso de diseño, si se trata de esquemas UML o DB, diagramas de clases y documentos de texto con especificaciones y similares.

Voy a enumerar la razón de mi jefe para no documentar:

1. lleva mucho tiempo: concéntrese en implementar
2. si el diseño cambia - entonces la documentación debería cambiar, doble problema
3. al final solo obtienes cientos de páginas que nadie quiere leer, y nadie edita realmente, así que para cuando esté desactualizado
4. Es un dolor, nadie realmente quiere hacerlo

Ahora me doy cuenta de que trabajamos más rápido, pero también recuerdo el tiempo que llegué aquí y me sumergí directamente en algún código antiguo, sin entender nada.

En realidad, todavía no obtengo la mayoría de este código antiguo, y a veces cuando entro veo muchos parches de diferentes desarrolladores que intentan hacer pequeños ajustes.

Realmente creo que la falta de documentación promueve este tipo de parches y la falta de comprensión del sistema en un sentido amplio.

mi pregunta es:

¿Cómo podemos equilibrar la documentación para promover el conocimiento continuo entre el equipo y seguir siendo rápidos y eficientes?

He encontrado CUALQUIER documentación es mejor que NINGUNA documentación. La cantidad apropiada generalmente está determinada por la cantidad de tiempo que tenemos para hacerlo o por cuánto odiamos las llamadas telefónicas y los correos electrónicos de soporte.

Parece que los miembros de su equipo actual tienen algunas expectativas poco realistas de sus recuerdos, o están avergonzados de sus habilidades de escritura y no están dispuestos a practicar.

Me doy cuenta de que estoy en una minoría (especialidad inglesa que ingresó a la ingeniería de software en la escuela de posgrado) aquí, ya que no encuentro documentación como una tarea rutinaria. Es una valiosa herramienta profesional. Puede que no encuentre la escritura tan difícil de hacer como algunos de mis compañeros de trabajo, pero eso es principalmente porque tengo más práctica en ello. No considero que un proyecto esté terminado a menos que tenga documentación, y generalmente lo escribo por razones puramente egoístas: para que pueda darles a las personas algo para leer en lugar de recibir llamadas telefónicas y correos electrónicos, o así puedo recordar de qué hablamos al final mes, más o menos, puedo referirme a cómo hice algo si necesito apoyarlo en medio de la noche.

La mejor manera de abordar la documentación es escribirla A medida que avanza, exactamente como escribir el código de prueba. Es sorprendente cómo algunas plantillas preescritas (con encabezados, códigos, etc.) pueden hacer que la documentación sea más fácil y rápida. De esta manera, puede capturar el cambio a medida que sucede, y tiene menos terreno que cubrir con el tiempo. Usted es más eficiente de esta manera, ya que puede consultar la documentación según la necesite y cambiarla en el camino. Hacerlo en una wiki, por ejemplo, hace que las actualizaciones sean más fáciles, y puede evitar problemas con la versión del documento si la última y mejor siempre está en línea en el mismo lugar, y puede enviar enlaces a las personas que necesitan leerla.

Si pasa un poco de tiempo documentando, TODO trabajará más rápido, especialmente cuando alguien nuevo se una al equipo, ya que no tendrá que pasar todo ese tiempo averiguando todo. Resolver las cosas es una parte divertida de nuestros trabajos, pero no es divertido cuando tienes que hacerlo con prisa para arreglar la producción. Todos ahorraríamos mucho tiempo si todos escribiéramos un par de notas más.

¿Su equipo tiene los mismos problemas con las pruebas o al escribir el código de prueba? Si no, esta será una venta más fácil.

Su documentación es útil de muchas maneras:
1) Para usted, ahora mismo, y para sus compañeros de trabajo, mientras trabaja en el proyecto.

2) A sus clientes. Tener documentación (incluidos los diagramas) que puede mostrar a los usuarios facilita las discusiones en las reuniones, especialmente si se trata de sistemas complicados. Incluso si la documentación está incompleta, es un lugar para comenzar.

3) A las personas que heredarán su trabajo (que incluso puede ser usted, en tres años). Muchos de mis compañeros de trabajo más jóvenes piensan que recordarán cosas para siempre. Sé que no lo recordaré más allá de esta semana si no lo escribo. Tener documentación le ahorra tener que pasar medio día para recordar cómo estructuró algo y tener que resolverlo todo de nuevo.

4) Para usted y otros, si la situación se vuelve política o contenciosa. Como alguien que toma notas en las reuniones, para mantenerme despierto y luchar contra el aburrimiento, a menudo he sido el único con la versión escrita de una decisión. La persona que lo escribió gana la disputa. ¿Recuerdas esto la próxima vez que alguien diga "Recuerdas esa reunión que tuvimos el invierno pasado en la sala de conferencias 4, cuando íbamos a pasar por X? Fred estaba allí, ¿y quién es ese tipo de Contabilidad?"

En mis últimos empleadores, hemos tenido un wiki de "desarrollo". Trozos importantes de funcionalidad (nuevo feed de importación / exportación, cómo funciona el subsistema de seguridad, dónde almacena el sistema los documentos cargados, etc.) se documentan allí. Por lo general, es un elemento obligatorio que se debe completar antes del paso de revisión del código. Por lo general, hay un poco de resistencia al principio, pero una vez que alguien necesita buscar un poco de información y está ahí, tienes otro converso.

Lo bueno de tenerlo en un formato wiki es que estás mucho menos inclinado a hacer todo el bonito formato de Word y tal cosa, y solo escribir la información real que necesitas guardar. La mayoría de los paquetes wiki (si no todos) le permitirán cargar documentos o imágenes (como diagramas UML de Visio o esquemas de interfaz de usuario), para que también pueda tener piezas visuales.

Como la mayoría de las cosas, creo que debes apuntar a hacer la cantidad mínima que podría funcionar. Sin embargo, eso no es lo mismo que ninguno.

No puede escapar de asignar tiempo para escribir la documentación adecuada. Equilibre lo que desee según la cantidad de trabajo que le den, pero deje un buen 15-20% de su tiempo para documentar lo que ha hecho. Todos en el equipo deben estar de acuerdo con esto, incluido su gerente, de lo contrario, solo documentará en beneficio de los demás y no obtendrá nada a cambio. La documentación debe ser una parte integral de su proceso de desarrollo.

La documentación debe decirle POR QUÉ hizo algo mientras deja la parte CÓMO para el código real y QUÉ parte para las pruebas unitarias. Cualquier cosa más es un dolor. Esto suele ser lo suficientemente bueno para las personas inteligentes que solo quieren un punto de partida.

Además, no olvide mantener una arquitectura general de alto nivel de cada componente grande de su base de código. Hace que sea muy fácil inducir a nuevos miembros del equipo.

Finalmente, cada vez que agregue una solución extraña, enlace a su base de datos de errores desde un comentario, muy útil.

Su jefe tiene razón, no imprima ninguna documentación UML que nadie leerá. Lo que hacemos en nuestro equipo es navegar en vivo en el modelo usando vistas de diagrama de clase. El principio es actualizar siempre MOF, el modelo UML en vivo desde el código y dejar que el diagrama de clases solo sea un visor del modelo, pero no el modelo en sí.

Funciona realmente bien porque toda la complejidad se realiza en backoffice a nivel de modelo. Puedo refactorizar mi proyecto, escribir java doc o escribir documentación uml en el modelo. Es una especie de clic y listo. Cuando haces clic obtienes la documentación en vivo. Si algo no está claro, entonces abro el diagrama de clase y empiezo a jugar con él. Eliminar de los clasificadores de diagrama, agregar nuevos clasificadores, acercar y alejar, mostrar asociación, eliminar asociación, etc. El modelo no cambia porque no creo ninguna información de modelo nuevo, solo los uso.

Es realmente importante abrir el diagrama de un paquete y poder leer directamente en el diagrama de clase un comentario sobre lo que se supone que es esta clase. Qué se supone que debe hacer este método y cuál es el flujo, etc.

UML es genial, realmente útil, pero deberíamos dejar de usar Model Driven Devleopment para dar más flexibilidad y más iteración en las etapas de modelado / desarrollo. El diagrama de clase se actualiza en vivo desde el código y la documentación siempre es precisa y está disponible con solo un clic. No mencionaré una herramienta, pero si usa Java y Eclipse, es fácil encontrar qué herramienta uso :-)