Pensando en la documentación técnica como grafos

Lo he dicho ya varias veces, me he cansado de los words como documentación. Personalmente veo la documentación como un grafo de conocimiento vivo y alimentado por todo el equipo. Un grafo inteligente al que se le podría hacer preguntas.

documentationAsGraph

¿Qué representarían los nodos del grafo y qué información almacenarían?

En el grafo que sería la base de conocimiento del equipo cada nodo podría ser un concepto, un término, una pieza de la documentación técnica… Cualquier elemento al que se referencie siempre y de forma única porque, por ejemplo, no deberían haber dos guías de cómo usar Puppet en un proyecto de la organización.

Cada nodo almacenaría la URL donde estaría el texto de la documentación, el nombre de su autor, la fecha de la última modificación y la fecha de obligada revisión:

(howToPuppet:GUIDE {
name:"HowTo Puppet in a new project",
url:"doc://howtopuppet/",
author:"Jonás",
lastModified:"20160505",
revisionOn:"20160601"
})

En el ejemplo, aparezco como autor de una guía ficticia sobre cómo usar Puppet en un nuevo proyecto dentro de la organización. La última fecha de modificación indica cómo de actualizado está el documento y revisionOn establece una fecha en la que debería ser revisado para actualizar información obsoleta. Al grafo se le podría preguntar qué documentación tiene que ser revisada en una cierta fecha:

MATCH (docsToBeRevised)
WHERE docsToBeRevised.revisionOn <= "20160601"
RETURN docsToBeRevised.name

O quién es el gurú de cierto tema en el equipo preguntándole al oráculo quién ha modificado últimamente más documentación relacionada con un nodo concreto:

MATCH (n)-[*..2]-(f) WHERE n.name = "Puppet"
RETURN f.author AS Author, count(f.author) AS Docs
ORDER BY count(f.author) DESC LIMIT 1

Podemos jugar con grafos en la consola de neo4j, escribiéndolos en Cypher que es el lenguaje de consulta estilo SQL con el que también he creado un GraphGist muy sencillito para verlo en acción.

Anuncios

Por una mejor documentación

Echo de menos que a los documentos técnicos no se le aplique el mismo rigor que al código que se desarrolla. Esto ocurre tanto en proyectos donde el negocio es el propio software como en proyectos donde el negocio es otro.

Igual que se usa Excel para todo, se usa siempre Word para mantener la documentación, sea guía de usuario, especificación técnica o normas empresariales. Al trabajar con esta documentación encuentro un montón de problemas:

Que haga falta Microsoft Word para poder ver el documento. Una documentación escrita en HTML se puede leer con cualquier navegador desde cualquier dispositivo.

Que se vean mil estilos diferentes dentro del documento. Con un buen conjunto de estilos predefinidos en CSS se evitaría que un usuario sin querer añada estilos extraños al documento. Además, utilizar características de los preprocesadores como las variables ayudan a que los estilos se diseñen con la precisión milimétrica que un ingeniero debe aplicar.

Que dos documentos de la misma empresa escritos en diferentes épocas tengan diferentes estilos. Un archivo de estilos CSS centralizado para todos los documentos evitaría la necesidad de actualizar los estilos de los documentos porque cambien los colores corporativos de la empresa.

Una tabla poco fiable de historial de versiones dentro del documento. Utilizar un sistema de control de versiones de verdad ayuda a recuperar versiones anteriores del documento y a entender cómo y por qué el documento está evolucionando.

Que los documentos se diseñen para ser imprimidos en lugar de para ser consultados. Una interfaz HTML aporta interactividad para navegar por el documento sin perder la capacidad de que se pueda imprimir teniendo un conjunto de estilos específicos para dicho formato.

Que haya información redundante ya sea porque haya varias definiciones de un mismo concepto o porque el mismo concepto tenga diferentes nombres a lo largo de todo el documento. Ya sabéis que en desarrollo de software, dos métodos que hagan lo mismo es pecado.

Con HTML, cada concepto puede ser un único archivo y cada vez que se nombre ese concepto en la documentación se enlazará a ese archivo (como Wikipedia = MediaWiki con la sintaxis [[]]).

Está claro que no todos los empleados que escriben documentación son técnicos y pueden encontrar dificultad en utilizar un sistema así. Creo que sería labor del departamento técnico educar para que se use un sistema de conocimiento correctamente porque uno de los mayores tesoros de una empresa es el know-how y mantener una documentación pobre y poco fiable no ayuda a nadie.

Modas, APIs y documentación pobre

Llevan ya tiempo de moda las APIs basadas en servicios web REST. El punto fuerte es que uno se comunica con la API usando el protocolo HTTP con lo que para casi todos los lenguajes existen librerías muy maduras para hacer que obtener datos de servicios web sea muy sencillo.

Implementar una API REST es bastante rápido y cuando a uno le ponen algo fácil, se acostumbra y lo quiere todo fácil como la documentación. Es verdad que la documentación es otra porción del software que hay que mantener y cuanto más ligera sea, menos que corregir en el futuro. De hecho, el manifiesto ágil expresa que el código funcionando es la mejor documentación y en TDD la documentación son las mismas pruebas unitarias. Pero todo tiene un límite. Mi límite lo encontré con la API de Stereomood, pero ahí fuera hay muchos ejemplos más. Mi último ha sido la API de Coinbase que no es de las peor documentadas pero también deja bastante a la imaginación.
El protocolo OAuth tiene dos formas de uso principales: two-legged y three-legged. La forma de uso común es three-legged indicada para widgets y complementos. Sin embargo, si el desarrollo es una aplicación que cuenta con almacenamiento propio, puede ser más fácil usar two-legged OAuth. Pues la cosa es que three-legged está muy bien contemplado por la documentación de Coinbase, sin embargo, la otra no.
Aquí es donde entra Github para echar una mano y es que, a parte de poder consultar el código de la aplicación oficial para Android, también encontré otra aplicación no oficial para Android que sí que implementaba two-legged OAuth.
Hay que currarse un poquito más las documentación, que no todo en esta vida es el caso típico. Que una API sea fácilmente configurable y flexible en cuanto a distintas formas de uso es un valor que las distingue de las demás.