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

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s