Documentación ágil

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?

Tagged:
  • Ivanator

    Si el documento tiene un formato más tradicional, distribuible e imprimible (un PDF, un ODT o un DOC), es decir, no es una entrada en un blog o una wiki, hay que usar siempre un número de versión en un lugar visible del archivo y de la copia impresa.

    Un problema típico es que clientes o colaboradores se vuelvan locos buscando algo en una versión incorrecta y que no haya una manera fácil de controlar cuál es.

    Cuando distribuyo documentos más o menos formales, suelo poner una tabla (visible) con metadatos en la primera página incluyendo cosas como: nombre del doc, versión, autores, datos de contacto, tipo de distribución (interna, externa), número de páginas, palabras clave y un pequeño resumen.

  • Jose Manuel Beas

    Si me permites, yo pondría el pequeño resumen en la mismísima portada. En la práctica resulta utilíssssimo. 🙂

  • Antonio Muñiz

    Hola José Manuel,

    Yo incluiría una más: si el documento no aporta nada, procura por todos los medios no tener que hacerlo.

    Esta situación se da con clientes cuyo sistema de gestión de la calidad les hace comprobar la entrega de una serie de documentos, apliquen o no apliquen (no es más que un tick en una checklist).

    A veces es fácil argumentar la “no necesidad” del documento, en otras no tanto y al final hay que hacerlo 🙁

    Un saludo.

  • Jose Manuel Beas

    Cierto, y si efectivamente el cliente lo quiere, lo quiere, lo quiere… pues se estima una historia de usuario y que sepa cuánto le cuesta el documento, porque muchas veces pensamos que la documentación no tiene coste (al menos nos comportamos como si eso fuera así y prometemos documentos y más documentos que luego no nos da tiempo a elaborar con un mínimo de calidad aceptable).

  • mostofreddy

    Muy bueno el post.

    Yo agregaría, teniendo en cuenta que la documentacion del codigo es bastante imporatante en las metodologias agiles, utilizar algun framework que permita automatizar esto, como javaDoc o phpdocumentor.

    Tenes toda la razon Jose, es muy comun, al presupuestar un proyecto, nos olvidemos del tiempo y los costos que lleva hacer la documentación por mas mínima q sea.