Microsoft marca el camino a seguir en documentación técnica

El nuevo servicio documental de Microsoft es mucho más que un cambio estético en la plataforma de contenidos.

La pasada semana, Microsoft dio a conocer su nueva plataforma documental docs.microsoft.com. Este cambio, detallado en la primera entrada del blog del equipo, incluye elementos que no resultan novedosos en sí mismos, pero que sí lo son cuando se trasladan al ámbito de la documentación técnica. El aspecto de la documentación es ahora más parecido al de un blog que al del clásico documento técnico, con artículos más cortos y la incorporación de elementos como el tiempo de lectura de cada artículo, tipografías de mayor tamaño y diversas herramientas de comentario que recuerdan instantáneamente a Medium.


Las nuevas opciones de comentario y petición de cambios se añaden al clásico cuadro de sugerencias al final de cada artículo (que se mantiene). Con todas estas opciones y la posibilidad de añadir notas a cada párrafo no queda claro, sin embargo, qué respuesta pueden esperar los usuarios y cómo se integrarán las sugerencias enviadas en el documento final.

Pero la novedad más relevante no es estética. La gestión de cambios se realiza ahora desde GitHub, lo que permite solicitar revisiones del documento fuente mediante peticiones pull en la plataforma. Y todo ello aprovechando la sencillez de Markdown, lenguaje cuyo uso se está popularizando en los últimos años. Este uso de la plataforma GitHub no es nuevo -de hecho, Microsoft lo utilizaba ya en otras partes de su documentación-, pero por su generalización y la importancia de Microsoft, marca un punto de inflexión y un camino a seguir por otros fabricantes.

Jeff Sandquist, autor del artículo, señala también que los cambios incorporados no son sólo estéticos o de funcionalidad, sino también de contenido. Aunque no es mucho más lo que se dice sobre este aspecto, el comentario parece indicar que la documentación estará más orientada a la realización de tareas, algo que se puede ver ya en los artículos técnicos de Azure.

Aquellos que, de una u otra forma, trabajamos con la documentación del fabricante, hemos visto cómo se sucedían pequeños cambios en los últimos años, pero sin ninguna transformación significativa. Microsoft acomete así una transición necesaria, después de un tiempo en los que sus tres grandes áreas documentales -TechNet, MSDN y más recientemente, Azure- parecían evolucionar por caminos distintos.

El contenido de la nueva plataforma es aún escaso, pero los cambios introducidos apuntan a una documentación más adaptada a las necesidades del usuario, mejor estructurada y posiblemente con menos errores, gracias a las nuevas herramientas de comentario.


(este artículo fue publicado originalmente en LinkedIn el 11-05-2016)