Docs as Code en Linode

Me llamo Nathan y soy miembro del equipo de redacción técnica de Linode. Uno de nuestros principales trabajos es contribuir y mantener la biblioteca de guías y tutoriales en https://www.linode.com/docs, donde se publican más de 1.400 artículos. Para mantener la calidad del contenido y fomentar la colaboración en el proceso de redacción, hemos adoptado una metodología de docs as code para nuestro flujo de trabajo de autoría.

Docs as code es una metodología en la que las herramientas que se utilizan para escribir la documentación son las mismas que se utilizan para escribir el software. Esto incluye:

• Uso de software de control de versiones
• Escribir archivos de documentación en texto plano
• Ejecución de pruebas automatizadas
• Practicar la integración continua y la entrega continua

El equipo de redacción técnica deLinodetambién ha ampliado esta metodología asumiendo la responsabilidad de la infraestructura en la nube que aloja nuestro sitio web de documentos.

¿Por qué Docs as Code?

Seguir estas prácticas ofrece una serie de beneficios:

• Trabajar con estas tecnologías ayuda a crear un vínculo más estrecho entre el equipo de redacción técnica y los equipos de desarrollo e ingeniería de Linode.
  
• Otros equipos de Linode pueden contribuir a varios aspectos de nuestro proceso. Por ejemplo: el equipo de front-end puede ayudar a actualizar la temática/presentación del sitio web de documentos utilizando las herramientas con las que ya trabajan, y un miembro del equipo de ingeniería podría escribir nuevas pruebas automatizadas para la biblioteca de documentos.
  
• Nuestro equipo escribe con frecuencia guías y tutoriales sobre las tecnologías utilizadas en nuestro proceso. Implementarlas por nosotros mismos nos permite conocerlas mejor, lo que mejora nuestra capacidad para explicarlas.
  
• También tenemos que documentar con precisión los productos de Linode, lo que puede implicar la revisión del código base de Linode. El conocimiento de los lenguajes y herramientas utilizados en estos proyectos puede ayudarnos a comprenderlos mejor.

Nuestra aplicación

Dado que la aplicación de esta metodología puede variar entre las distintas organizaciones, me gustaría ofrecer un esquema detallado de nuestro proceso:

1. Creación: Nuestros redactores técnicos redactan las nuevas guías en Markdown. Markdown se utiliza para representar texto enriquecido en un archivo de texto plano, y puede ser compilado en HTML por una serie de herramientas. Markdown tiene una adopción casi universal en el desarrollo de software; por ejemplo, los archivos README de GitHub están escritos en Markdown. Escribir en Markdown también significa que puedes utilizar cualquier editor de texto plano que prefieras, desde editores de escritorio modernos como Visual Studio Code, hasta Emacs y Vim. Sabemos que la gente tiene fuertes opiniones sobre sus editores de texto preferidos, y esta flexibilidad ayuda a que más personas contribuyan a nuestra biblioteca.
   
2. Vistas previas de sitios locales: Los archivos Markdown de nuestra biblioteca se compilan en su representación final HTML con un generador de sitios estáticos. Los sitios estáticos son conjuntos de páginas preconstruidas que no dependen de una base de datos para ser generadas cuando se solicitan (como es el caso de un CMS como WordPress). Por ello, un sitio estático es muy rápido de cargar. Un generador de sitios estáticos genera un sitio estático combinando sus archivos de contenido (por ejemplo, Markdown) con un tema que usted especifica.
   
   El sitio web de docsLinodeutiliza Hugoque es uno de los generadores de sitios estáticos más populares:
   
   • Hugo ofrece métodos de instalación bien documentados en muchos sistemas operativos, por lo que no hay problemas cuando se incorpora un nuevo empleado.
     
   • Hugo incluye un servidor web de desarrollo local, para que los autores puedan renderizar el sitio en sus ordenadores mientras escriben nuevas guías. Este servidor también se recargará en vivo cada vez que el autor guarde su archivo.
     
   • Hugo es extremadamente rápido, lo cual es un factor significativo para una biblioteca de nuestro tamaño: mi Macbook Pro es capaz de compilar las 1400 guías en aproximadamente 3 segundos, y la función de recarga en vivo es casi instantánea. 
     
   • Los códigos abreviados de Hugo también nos ayudan a mejorar nuestras guías con características que Markdown no permite, como las notas resaltadas y los fragmentos de código numerados por líneas.
     
     
3. Colaboración: La biblioteca de documentos se almacena en un repositorio Git público alojado en GitHub, y cada autor mantiene un fork de este repositorio. Cuando un autor termina de redactar una guía, confirma sus cambios, los sube a su bifurcación y, a continuación, abre una solicitud de extracción en el repositorio principal.
   
   En nuestro proceso de redacción, dos miembros del equipo realizan una edición técnica y una edición de copia en cualquier guía nueva o actualización de la misma. Estos miembros del equipo descargarán la rama de la solicitud de extracción, harán y confirmarán sus cambios, y luego los enviarán a la rama en GitHub. Git es otra herramienta casi universal para el desarrollo, y su uso nos permite aprovechar algunas de las mejores prácticas estándar para la colaboración, como el flujo de trabajo gitflow.
   
   Además, la popularidad de GitHub significa que tiene un gran número de integraciones útiles. En particular, utilizamos Netlify para generar vistas previas automáticas y accesibles al público para cada solicitud de extracción. A menudo necesitamos pedir la opinión de los linodianos en diferentes departamentos, y ellos pueden ver estos enlaces compartibles de Netlify sin tener que clonar nuestro repositorio de documentos e instalar Hugo en sus ordenadores portátiles.
   
   Por último, el alojamiento en un repositorio público abre nuestra biblioteca a colaboradores externos, lo cual agradecemos.
   
4. Pruebas: Cada vez que se envía o se actualiza un pull request, se ejecutan una serie de pruebas sobre el contenido del PR. Estas pruebas se ejecutan con Travis CIque es un servicio de integración continua que también ofrece integración con GitHub. Si alguna de estas pruebas falla, se bloquea temporalmente la fusión del pull request:
   
   • El contenido de la guía se revisa para comprobar la ortografía y el estilo (por ejemplo, las mayúsculas de los términos técnicos). Para realizar estas tareas utilizamos Vale, un linter de código abierto diseñado para trabajar con prosa. Cuando integramos Vale por primera vez, nos informó de más de 500.000 errores ortográficos en nuestra biblioteca. Aunque es un poco embarazoso, conocer esta cifra y poder actuar en consecuencia nos dio un gran impulso de confianza en nuestro contenido y en nuestro nuevo sistema de publicación.
     
   • Comprobamos la existencia de posibles enlaces rotos entre guías utilizando Scrapy, un framework de código abierto Python que raspa el contenido de los sitios web. Esta prueba fue escrita en colaboración con un miembro del equipo de ingeniería de Linode. Cuando implementamos Scrapy por primera vez, también encontramos una serie de enlaces rotos que pudimos corregir.
     
   • Otro script de Python comprueba que los metadatos de la portada de las guías son válidos y no tienen errores de sintaxis. Una sección de materia frontal rota puede causar problemas al construir el sitio, por lo que tener esto validado significa que podemos estar seguros de que el sitio se renderizará al actualizar los servidores web de producción.
     
5. Publicación y alojamiento: La actualización del sitio web de documentos se gestiona automáticamente mediante una colección de scripts que se activan a partir de determinados eventos en GitHub:
   
   • Cada vez que el contenido se fusiona en la rama maestra del repositorio principal de documentos, se envía una notificación de webhook a un servidor web de puesta en escena, que es un Linode. Este servidor web de ensayo extrae la rama maestra de GitHub y construye el sitio con Hugo, con la raíz del documento del servidor web como objetivo para el sitio renderizado. Vemos este sitio de puesta en escena y confirmamos que el contenido aparece como se espera.
     
     El servidor de puesta en escena no era inicialmente una parte de nuestro flujo de trabajo; se construyó después de un incidente que rompió temporalmente nuestro CSS / estilo durante una actualización del sitio de producción. En resumen, Netlify había renderizado correctamente una vista previa de la nueva versión del sitio, pero no detectó un problema de estilo. Esto se debió a que utilizó nuestra línea de construcción de "desarrollo", en lugar de nuestra línea de construcción de "producción" (que minifica nuestro CSS y otros activos). El nuevo servidor de ensayo está configurado con la misma configuración que nuestro servidor de producción, por lo que también utiliza el canal de construcción de producción, y detectará errores como éste.
     
   • Para actualizar el sitio de producción, creamos una nueva etiqueta de lanzamiento en GitHub. Esto desencadena otra notificación de webhook que se envía al servidor web de producción. Este servidor ejecuta una secuencia de comandos similar a la del servidor de ensayo, pero extrae el contenido de la nueva etiqueta de lanzamiento.
   • El hecho de que nuestra función de publicación se realice de forma automática minimiza cualquier error humano que pudiera producirse si tuviéramos que realizar este proceso manualmente. Los servidores de preparación y de producción se gestionan mediante fórmulas de configuración, lo que también minimiza los errores humanos cuando necesitan mantenimiento o actualizaciones de software. Salt fórmulas, lo que también minimiza el error humano cuando necesitan cualquier mantenimiento o actualización de software. Salt también es utilizado por otros proyectos de infraestructura en Linode , por lo que nuestros servidores web de docs pueden ser gestionados junto con otras partes de la flota.

La adopción de esta metodología nos ha ayudado a agilizar enormemente nuestro flujo de trabajo, pero siempre estamos trabajando para iterar y mejorarla. Si tienes alguna sugerencia sobre las actualizaciones que podemos hacer, ¡háznoslo saber! Estoy en el Slack de Write the Docs como nmelehan, al igual que otros miembros del equipo. Si quieres leer más sobre los documentos como código, te recomiendo la guía de Eric Holscher en el sitio web de Write the Docs.