Documentación degradante: ¿cómo lidiar con ella?

Importante : no tenemos ningún problema con la documentación del código fuente . Esto pertenece a la auditoría de código regular y se mantiene actualizado. Nuestro problema es con la documentación de los desarrolladores (o "externa" si lo desea), pequeños consejos tipo blog de programadores a programadores que tienden a escribirse una vez, a menudo se quedan atrás.

Usamos un sistema similar al wiki para producir documentación de programadores : artículos escritos por programadores para programadores que describen con un poco más de detalle cómo funciona un código en particular. Esas páginas wiki generalmente incluyen:

• motivaciones detrás de las decisiones de diseño para partes de API (por ejemplo; hicimos esto feo porque esta biblioteca de terceros en particular quiere que se hagan cosas de esta manera, porque esta otra biblioteca ..., porque ...)
• explicación de cómo lidiamos con tareas comunes particulares (por ejemplo, mostrar una ventana emergente trivial, que necesita hacer referencia a estilos de aplicación apropiados, registrarse en el componente de registro e implementar alguna interfaz para que otro componente la "escanee" automáticamente)
• buenas prácticas (subjetivo como es, en realidad escribimos esto)
• configuración del entorno, herramientas requeridas y su configuración

En general, principalmente cosas relacionadas con la escritura de código que no se ajusta a la documentación de código regular debido a su tamaño y naturaleza de publicación de blog / artículo.

El problema

En cuanto a la introducción de este sistema, parecía una buena idea hace unos meses, hoy en día siento que está causando más problemas de los que resuelve. Por ejemplo:

• las personas hacen artículos de escritura ... pero una vez cambiado el código, actualización wiki rara vez se sigue
• muchos artículos de scratch , escritos por alguien apurado y se fueron así
• A pesar de que la solicitud de artículos generalmente proviene del líder del proyecto, casi nunca se verifica su corrección / composición, lo que a veces resulta en una mala calidad

La degradación habitual. Código cambiado, wiki permanece igual. La próxima vez que alguien busque información, lo que generalmente encuentra es un montón de cosas desactualizadas y de baja calidad, y se pregunta qué está pasando, si las cosas que encontró son precisas o (aún peor) qué partes son. Y lo que se suponía que iba a ayudar, termina haciendo lo contrario.

Por el momento, parece que las personas son conscientes del problema, incluido el líder del proyecto, pero aparentemente nadie parece molestarse en hacer nada al respecto (o tiene cosas más interesantes que hacer).

Mi pensamiento inicial fue arrojarlo todo al olvido (después de que varias veces seguidas me picaran "consejos" obsoletos), pero supongo que eso podría ser demasiado extremo. A veces vale la pena tener en cuenta cierta información y una buena lectura, pero el problema sigue siendo el mismo: ¿cómo lidiar con su "actualización" ? ¿Se ha vinculado de alguna manera con el código fuente (de modo que cuando se registra la versión actualizada del archivo, se notifica al autor del artículo que podría necesitar revisar el código / artículo)? ¿La persona designada lo "vigila" en lo básico diario? Hacer limpiezas regulares?

Parece que estás documentando demasiadas curiosidades en la wiki.

Documentar bloques de código y métodos en el código . Intente que su código se documente automáticamente para que no tenga que hacer muchos comentarios. Escribir exámenes unitarios también puede ayudar.

Documente las decisiones de diseño y la arquitectura con mayor granularidad en la wiki, por lo que la wiki no necesita cambiar con frecuencia ni requiere mucho trabajo para cambiar. Si mucha gente en su equipo ya conoce la arquitectura y el equipo no está creciendo rápidamente, entonces puede que no haya un caso sólido para documentarlos, cara a cara suele ser la mejor transferencia de conocimiento.

Reescriba o elimine la información desactualizada de inmediato , como un código muerto, cuanto más tiempo permanezca, más difícil será detectar y más se acumulará. Si no tiene tiempo, simplemente elimínelo y marque el artículo como necesario volver a trabajar, lo ralentiza y de todos modos se almacena en el control de versiones.

Documente los procedimientos automatizándolos en un script o archivo de instalación. De lo contrario, manténgalos en la wiki, pero cada vez que alguien use un procedimiento de la wiki, dígales que intenten mejorar el artículo o automatizar partes del proceso.

Los artículos de blog pertenecen a blogs . Si la gente quiere compartir sus opiniones y consejos personales, cree un blog de la compañía para eso. Probablemente no quieran que sus artículos se modifiquen y nadie los modificará de todos modos, así que no dejes que abarroten la wiki.

La documentación debe tratarse como una entrega y, por lo tanto, sujeta a las reglas de trazabilidad y aceptación, así como a la cantidad de tiempo adecuada para desarrollarse.

No es raro ver a la gente "esperando" que la documentación del software sea un hecho, cuando no lo es.

Radical pero efectivo. Si alguien escribió un nuevo módulo pero no lo documentó, vuelva a abrir la tarea en el rastreador de problemas y, si es necesario, evite enviar todo el código fuente no documentado. Si permites que los desarrolladores traten la documentación del código fuente como un mal necesario, terminarás con fragmentos de documentación fragmentarios y obsoletos.

En mi proyecto reciente tendemos a rastrear al menos todas las bibliotecas de terceros necesarias. Si alguien introduce una nueva biblioteca, pero no está documentada, revertiremos la solución hasta que se presente la documentación. Sin un enfoque tan radical habría caos. Por ejemplo, un desarrollador sin experiencia podría usar una biblioteca cuya licencia está en conflicto con la licencia de nuestro software.

Si algo está cambiando rápidamente, no debe mantenerse fuera del código.

Motivaciones detrás de las decisiones de diseño para partes de API

Esto es especialmente importante para mantenerse cerca del código. Como en, en el mismo archivo fuente. De esa manera, será un poco más difícil de ignorar cada vez que alguien toque el archivo y generará menos envíos a TheDailyWTF por personas que no saben que existe la documentación externa.

La degradación habitual. Código cambiado, wiki permanece igual.

Aquí es donde la "documentación ejecutable" (pruebas unitarias) se vuelve muy útil. Si el código cambia y las pruebas no cambian junto con él, entonces la compilación se rompe. Por supuesto, escribir pruebas como documentación requiere cierta habilidad. Pero también lo hace escribir (buena) documentación externa.

Una buena manera de abordar el problema es hacerlo parte del proceso. Si tiene un seguimiento de código para / hacer referencia a las páginas relevantes en la wiki, un desarrollador puede averiguar fácilmente qué podría necesitar actualizarse. Además, haga que los revisores sean responsables en una revisión de código para asegurarse de que la wiki esté actualizada (con respecto a la actualización).

Otra forma de agregarlo como parte del proceso, ya que está utilizando un modelo ágil, parte del proceso de planificación para las iteraciones, podría ser actualizar los cambios planificados en la wiki. La wiki luego sirve como un recurso 'así es como deberían funcionar las cosas'.

Si está utilizando un lenguaje .net, mire ( Sandcastle ) que toma la documentación XML (/// en C #) y la convierte al formato de ayuda de MSDN.

El formato incluye descripción, comentarios y tiene la capacidad de incluir ejemplos de código, así como algunas otras características. Puede imprimir en formatos .CHM, .HsX, .MSCH y HTML / ASP.NET. El proyecto real se agrega a su solución y se crea en el servidor de compilación. Hemos hecho esto y desplegamos en un sitio web cada versión, y los consumidores lo adoran porque la documentación es relevante para la versión y se actualiza constantemente.

También puede especificar qué incluir en la documentación. Actualmente tenemos 2 proyectos: uno para consumidores externos que incluye solo los contratos y los elementos apropiados (clases, enumeraciones, etc.), y otro para desarrolladores internos que incluye todo en la API, incluidos los elementos marcados privados e internos.

Esta se ha convertido en la única documentación que utilizamos, ya que las motivaciones y peculiaridades sobre el uso de la API se pueden incluir en la sección Comentarios de la documentación. El proceso funciona bien donde yo trabajo.

Me centraría en dos áreas, 1) El código. 2) Notas y documentos sin código.

1) El código.

Intenta hacer que se auto documente. En el pasado descubrí que a menudo se aconsejaba pero rara vez se explicaba bien, así que ...

En lugar de este tipo de pseudocódigo:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Haga un código que se parezca más a esto:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

Utilice el control de fuente para rastrear la información de "quién hizo qué cuándo".

2) El no código

Use una wiki y un formato de descuento para mantener esta información. Hazlo parte del trabajo. Publíquelo, publíquelo y blogéelo. Configure una reunión estándar semanal o mensual para revisar cosas antiguas y nuevas. Conviértase en un mantra de que cuando alguien pregunta por algo, se da la respuesta ... junto con el pensamiento "¿debería estar en la wiki la próxima vez que alguien pregunte?"