Documentación ágil

Palabras clave:
Tiempo aproximado: 2 min.
En un artículo de un blog que encontré por casualidad, da unas cuantas pistas sobre cómo “agilizar” nuestra documentación.

  1. Si un documento es más largo de 20 páginas, por favor considera repartir el contenido en más de un documento.
  2. Si puedes decir lo mismo con menos palabras, por favor hazlo. (Usa patrones, por ejemplo)
  3. Si puedes decir lo mismo sin palabras, mejor. (Usa imágenes, diagramas…)
  4. Escribe para tu audiencia, no para ti mismo. No des por supuesto que sé lo que tú sabes.
  5. Si crees que puedes expresarlo mejor hablando, grábalo y enlazas a la grabación desde el documento. Igualmente, si crees que es mejor mostrar cómo se hace con una grabación en video o un screencast, adelante.
  6. Si mientras estás trabajando encuentras algo digno de ser registrado, blogéalo o ponlo en el wiki.

A éstas yo añadiría:

  1. Automatiza las pruebas para que sea posible entregar el informe correspondiente en cualquier momento.
  2. No tengas miedo a incluir una foto o un diagrama escaneado en un documento para un cliente (y mucho menos si es un documento de uso interno).
  3. Incluye un resumen del documento (al menos su propósito) en las propiedades del documento, así permites que se pueda indexar y realizar búsquedas.
  4. Incluye un resumen en la portada del documento, así permites que no sea necesario “bucear” en el documento para saber si es el que buscamos o no.
  5. Utiliza un repositorio para saber exactamente cuál es la última versión del documento.

¿Se os ocurre alguna más a vosotros?