La documentación no documentada

La documentación no documentada

Desde el inicio de los tiempos el conocimiento de la humanidad se ha transferido por medio de documentos a través de varias generaciones, sin esta información no tendríamos memoria histórica y al morir el experto, el conocimiento dejaría de existir con el.

Documentar es una de las actividades que los profesionales menos queremos y mucho menos valoramos. De hecho este trabajo siempre se deja para el final de todo proyecto y finalmente se realiza con el fin de dar cumplimiento a las clausulas del contrato y no para dar valor a quienes harán uso del conocimiento que generamos.

A continuación un resumen de las causas mas comunes por las cuales considero que la documentación generada en muchos casos no da valor:

• Falta de contexto: Normalmente quien documenta asume que sus lectores tendrán el mismo conocimiento sobre las características, beneficios, fortalezas, debilidades y condiciones de uso de su producto. Esto hace que sea muy complicado entender los diseños e instrucciones que se entregan.

• Asumir pre-condiciones de funcionamiento: Todo producto normalmente tiene unas pre-condiciones que deben satisfacerse de modo que este pueda funcionar adecuadamente. En el caso del software tales pre-condiciones serían las librerías de software usadas, contenedores, servidores de aplicaciones, sistemas operativos, IDE o cualquiera otra. ¿Acaso un vehículo puede funcionar sin gasolina?. Parece obvio, pero para un desconocedor no lo es.

• Asumir expertos: Está íntimamente relacionado con las dos anteriores pero me parece tan importante que quiero recalcarlo. Es mejor asumir que quien leerá la documentación es un completo desconocedor del producto. 

• Orientación a diferentes públicos: No todos los lectores tendrán los mismos intereses, de modo que debe ofrecerse mecanismos a través de los cuales la información pueda ser accedida rápidamente para cada tipo de público. Es muy importante en este caso tener un indice y referencias a diferentes partes del documento de modo que no sea necesario leer toda una sección para encontrar lo que se requiere.

• Fuentes de información adicional: Nada mas triste que tener dudas y no saber a quien o donde acudir, podría ser una persona, un sitio de internet o cualquier otra fuente de datos.

• Documentación de políticas y lineamientos: Normalmente durante el proceso de construcción se realizan acuerdos que terminan siendo políticas (Se debe cumplir en todo los casos) y lineamientos (Recomendaciones para operar de forma adecuada). Conocerlos es muy importante y ayudan a entender la razón por la que se tomaron ciertas decisiones.

• Lo mejor son los ejemplos: Un ejemplo vale mas que mil palabras. Preferiblemente el ejemplo debe tener imágenes e instrucciones paso a paso de como realizar las tareas mas criticas tales como configuración del producto y en el caso puntual del software, construcción de funcionalidades complejas.

• Limitar la carreta: La introducción, justificación y cualquier otra información que no genera valor directo debe limitarse. Se debe documentar solo aquello que realmente será de utilidad.

• Información articulada: De nada sirven un conjunto de conceptos y definiciones si no están articulados dentro de un contexto. La mejor forma de articularlos es a través de un ejemplo.

• Glosario: Cualquier concepto propio del dominio debe documentarse claramente de modo que quien lea sepa de que le están hablando.

• Actualización: De nada sirve un documento desactualizado, con seguridad nadie lo volverá a leer. Esto va íntimamente relacionado con limitar la carreta. Mientras menor cantidad de información debamos modificar cada vez, mayor será la probabilidad de que lo hagamos

• Detalles: Si el conocimiento que queremos plasmar es muy cambiante no tiene mucho sentido desgastarnos en documentar el detalle (Porque tendremos que ajustar la documentación muchas veces). En estos casos es preferible plasmar un conocimiento de alto nivel que será complementado mediante conversación entre el experto y el que lo requiere.

• Conversación: Nada podrá reemplazar la interacción entre individuos, de modo que aún cuando esté muy bien documentado siempre será mejor conversar y discutir las dudas que con seguridad después de leer un documento serán bastantes.