En un artículo de un blog que encontré por casualidad, da unas cuantas pistas sobre cómo “agilizar” nuestra documentación.
- Si un documento es más largo de 20 páginas, por favor considera repartir el contenido en más de un documento.
- Si puedes decir lo mismo con menos palabras, por favor hazlo. (Usa patrones, por ejemplo)
- Si puedes decir lo mismo sin palabras, mejor. (Usa imágenes, diagramas…)
- Escribe para tu audiencia, no para ti mismo. No des por supuesto que sé lo que tú sabes.
- 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.
- Si mientras estás trabajando encuentras algo digno de ser registrado, blogéalo o ponlo en el wiki.
A éstas yo añadiría:
- Automatiza las pruebas para que sea posible entregar el informe correspondiente en cualquier momento.
- 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).
- 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.
- 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.
- Utiliza un repositorio para saber exactamente cuál es la última versión del documento.
¿Se os ocurre alguna más a vosotros?