Cómo automatizar el flujo de trabajo de documentación para desarrolladores

Para aprovechar al máximo este tutorial, debe estar familiarizado con: Git, GitHub y Linux y la línea de comandos.

¿Por qué debería preocuparse por la documentación de alta calidad?

Muchos equipos luchan con la escritura de la documentación . Cuando vaya a verificar un marco, la documentación a menudo estará desactualizada o poco clara. Esto puede generar frustración interna cuando un miembro del equipo intenta agregar una función, pero no entiende cómo funciona la función actual debido a la documentación deficiente. Esto puede conducir a horas improductivas en el trabajo.

La mala documentación también compromete una buena experiencia del cliente. Según Jeff Lawson, autor de Ask Your Developer y fundador de Twilio, si está vendiendo una API como producto, la documentación es el mejor anuncio para las partes interesadas técnicas . IBM realizó un estudio sobre la importancia de la documentación y el 90% de los encuestados admitió que tomaba sus decisiones de compra en función de la calidad de la documentación de un producto.

Escribir una buena documentación es importante para el desarrollador y las experiencias del cliente.

Si la documentación es tan importante, ¿por qué los equipos de ingeniería le restan prioridad?

Escribir documentación puede sacar a los desarrolladores del "flujo". La documentación a menudo se encuentra fuera de la base de código principal y es engorrosa de encontrar y actualizar. Ponerlo en una hoja de cálculo de Excel o en un CMS propietario no es raro.

La automatización de la documentación y la mejora del flujo de trabajo de la documentación solucionan esto.

Automatización de la documentación desde un alto nivel

¿Qué significa automatizar la documentación? Significa adoptar prácticas comunes de desarrollo de software. Cuando automatiza la documentación, está:

• escribir su documentación en Markdown;
• usar una canalización de integración e implementación continuas (CI/CD) para ejecutar tareas como la corrección de errores y la implementación de actualizaciones (en este tutorial, destacaremos las acciones de GitHub);
• implementar herramientas como Vale para hacer cumplir una guía de estilo y corregir errores gramaticales comunes.

Las guías de estilo

Antes de usar herramientas como Vale y GitHub Actions para automatizar la guía de estilo, tomemos un momento para definir qué es exactamente una guía de estilo.

¿Conoces esa sensación cuando estás escribiendo documentación y algo parece un poco fuera de lugar? Sus explicaciones no se ajustan al resto de la documentación, pero no puede describir por qué están equivocadas. La escritura explica el concepto, pero no parece encajar.

Cuando tiene este sentimiento, su voz y tono pueden estar apagados . Refinar la voz y el tono es una forma de hacer que la escritura suene cohesiva incluso si está desarrollando documentación que ha sido editada por los equipos de control de calidad, ingeniería y producto. A continuación se muestra una guía de estilo de ejemplo de la aplicación de autobús urbano TAPP, tomada del libro Escritura estratégica para UX de Torrey Podmajersky.

TAPP es una aplicación de tránsito (para autobuses y trenes). El encabezado de la tabla anuncia los valores de TAPP como empresa, ser eficiente, confiable y accesible. El lado izquierdo de la tabla enumera las diferentes partes cubiertas por la guía de estilo: conceptos, vocabulario, verbosidad, gramática y puntuación.

Juntos, estos hacen una guía de estilo . El encabezado presenta los valores y el lado izquierdo de la tabla muestra los diferentes componentes que encontraría en cualquier material escrito: vocabulario, gramática y puntuación. La belleza de esta guía de estilo es que los ingenieros y redactores sabrán claramente qué mayúsculas y qué puntuación usar para promover la identidad de la marca Tapp.

Guía de estilo de escritura técnica

No todas las guías de estilo vienen en tablas. Microsoft tiene un sitio web completo que sirve como una guía completa, que cubre todo, desde acrónimos hasta comunicación sin prejuicios y chatbots. Por supuesto, Microsoft no es la única empresa que tiene una guía de estilo. Google también tiene uno.

El problema con las guías de estilo

Las guías de estilo son un excelente punto de partida para las empresas que se toman en serio la documentación. Resuelven gran parte de la confusión que los desarrolladores pueden tener sobre cómo escribir exactamente sobre una característica importante que están impulsando.

El problema con las guías de estilo es que agregan fricción al proceso de escritura. Muchos escritores, incluyéndome a mí, no se molestan en dejar de escribir y mirar la guía de estilo cada vez que tienen una pregunta. A veces, una guía de estilo es engorrosa y demasiado difícil de consultar; por ejemplo, la Guía de estilo de Microsoft tiene más de mil páginas.

Linters y CI/CD para documentación

Si eres programador, probablemente estés familiarizado con los linters. Los linters son una forma ideal de hacer cumplir los estándares de codificación en su equipo. Lo mismo ocurre con la documentación. Cuando crea un linter, está estableciendo un punto de referencia de calidad para su documentación. En este tutorial, vamos a utilizar el linter de Vale.

Es común usar algún tipo de automatización de documentación junto con un linter. Cuando decimos automatización en este contexto, nos referimos al flujo de trabajo de integración continua e implementación continua (CI/CD). CI automatiza la construcción y prueba de la documentación . CD automatiza la liberación de código.

Puede usar muchos tipos diferentes de aplicaciones para implementar un flujo de trabajo de CI/CD. En este tutorial, usaremos GitHub Actions para ejecutar nuestra documentación linter. GitHub Actions ejecuta CI directamente en un repositorio de GitHub, por lo que no es necesario utilizar una aplicación de terceros, como CircleCI o Travis.

Finalmente, las Acciones de GitHub están basadas en eventos , lo que significa que se activan cuando sucede algo, como cuando alguien escribe una solicitud de extracción o un problema. En nuestro ejemplo, se producirá una acción de GitHub cuando alguien envíe cambios a su rama principal.

Acciones de GitHub

Primero, cree un repositorio de GitHub. Luego, localmente, cree una carpeta y cd en ella.

 mkdir automated-docs cd automated-docs

Una vez que esté en la carpeta, inicialice el directorio para Git.

 git init

Una vez que haya inicializado el repositorio, proceda a crear un directorio de flujo de trabajo en su carpeta.

 mkdir .github/ && cd .github/ && mkdir workflows/ && cd workflows/

Los flujos de trabajo son donde almacenaremos todas nuestras acciones de GitHub. Una vez que haya creado una carpeta de workflows de trabajo, cree un nuevo flujo de trabajo. Vamos a nombrar este flujo de trabajo vale.yml .

 touch vale.yml

Vale.yml es un archivo YAML. En este archivo de flujo de trabajo, incluiremos acciones y trabajos.

Ahora, abra vale.yml en su editor de texto favorito.

 nano vale.yml

Copie y pegue lo siguiente en vale.yml y repasemos el contexto y la sintaxis.

 # This is a basic workflow to help you get started with Actions name: CI # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project. env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

• name
  Este es el nombre, o como llamamos a nuestro flujo de trabajo. es una cadena
• on
  Esto controla el flujo de trabajo y los disparadores.
• jobs
  Aquí es donde establecemos y controlamos nuestras acciones. Seleccionamos el entorno donde se ejecutarán nuestras acciones; por lo general, es una buena apuesta optar por Ubuntu. Y aquí es donde añadiremos nuestras acciones.

GitHub tiene una guía sobre todas las demás sintaxis y variables del flujo de trabajo, en caso de que tenga curiosidad.

En esta sección tenemos:

• aprendió qué son las acciones de GitHub,
• creamos nuestro primer flujo de trabajo de GitHub,
• identificó las partes más importantes de un archivo YAML de flujo de trabajo de GitHub.

A continuación, vamos a personalizar nuestro flujo de trabajo de GitHub para usar Vale.

Configurar Vale en el archivo de acciones de GitHub

Una vez que hayamos copiado el archivo de flujo de trabajo base, es hora de personalizarlo, para que podamos comenzar a usar las acciones de Vale. Lo primero que debe hacer es cambiar el nombre del archivo YAML a Docs-Linting .

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting

A continuación, queremos ejecutar la prueba de Vale una vez que alguien haya enviado sus cambios a la rama principal en GitHub. No queremos que la prueba se ejecute cuando alguien crea una solicitud de extracción, por lo que eliminaremos esa parte del archivo YAML.

 on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ]

La sección de jobs es la parte principal del archivo de flujo de trabajo y es responsable de ejecutar las acciones de GitHub.

 jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master

Estas acciones se ejecutarán en la última versión de Ubuntu. La acción Checkout verifica el repositorio para que el flujo de trabajo de GitHub acceda a él.

Ahora es el momento de agregar una acción de Vale a nuestro flujo de trabajo de GitHub.

 - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Hemos llamado a nuestra acción Vale . La variable uses muestra qué versión de Vale vamos a implementar; idealmente, deberíamos usar la versión más reciente. En la variable with , establecemos debug en true .

La sección de styles nos da la opción de agregar una guía de estilo a Vale. En este ejemplo, vamos a utilizar write-good y la guía de estilo oficial de Microsoft. Tenga en cuenta que también podemos usar otras guías de estilo.

La parte final de esta acción de GitHub es env . Para ejecutar esta acción de GitHub, debemos incluir un token secreto.

Así es como debería verse el resultado:

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: jobs: prose: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Una vez que haya terminado de hacer cambios, guarde el archivo, confirme con Git y envíe sus cambios a GitHub.

 git add .github/workflows/vale.yml git commit -m "Added github repo to project" git push -u origin main

En resumen, en esta sección tenemos:

• activó la acción para que ocurra cuando insertamos un nuevo código en la rama main ;
• agregó una acción de Vale, configurando la debug en true e identificando guías de estilo;
• agregó un token de GitHub;
• cambios confirmados y enviados a GitHub.

En la siguiente sección, vamos a crear un archivo de configuración de Vale.

Configuración del archivo de configuración de Vale

Vaya a la raíz del directorio de su proyecto y luego touch .vale.ini . Abra .vale.ini en un editor de texto. Copie y pegue lo siguiente en .vale.ini :

 StylesPath = .github/styles MinAlertLevel = warning [formats] Markdown = markdown [*.md] BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
StylesPath proporciona la ruta de los estilos de Vale.
• MinAlertLevel = warning
  El nivel mínimo de alerta muestra la escala de gravedad de las alertas. Las opciones son suggestion , warning y error .
• [formats]
Markdown = markdown establece el formato como Markdown.
• [*.md]
  La configuración BasedOnStyles = write-good, Microsoft ejecutará write-good y la guía de estilo de Microsoft en todos los archivos Markdown que terminen en .md .

Esta configuración es lo mínimo. Si está interesado en obtener más información sobre la configuración de Vale, diríjase a la documentación.

Cuando haya terminado de hacer cambios, guarde el archivo, confirme y envíe a GitHub.

 git add .vale.ini git commit -m "Added Vale config file" git push -u origin main

En esta parte, hemos aprendido los aspectos internos de un archivo de configuración de Vale. Ahora es el momento de crear documentación de muestra.

Crear documentación y activar las acciones de Vale GitHub

¡Ahora es el momento de ver Vale y GitHub Actions en acción! Vamos a crear un archivo Markdown y llenarlo con texto. Y vamos a recibir nuestro mensaje de texto de DeLorean Ipsum.

Vaya a la raíz de su proyecto y luego touch getting-started.md . Una vez que haya creado el archivo getting-started , vaya a DeLorean Ipsum y cree un texto ficticio para su documentación. Luego, regrese a su editor de texto y pegue el texto en getting-started-md .

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all exactly twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Guarde el archivo, confírmelo y envíelo a GitHub.

 git add getting-started.md git commit -m "first draft" git push -u origin main

Una vez que haya realizado los cambios, diríjase a GitHub, donde se encuentra su repositorio. Vaya a la pestaña Actions .

Verá todos sus flujos de trabajo en el lado izquierdo. Solo tenemos uno, llamado Docs-Linting , el mismo nombre que pusimos en el archivo vale.yml .

Cuando empujemos la documentación a GitHub, activaremos la acción.

Si la acción se ha ejecutado sin ningún problema, obtendremos una marca de verificación verde.

Haga clic en "Documentos agregados" para obtener un informe completo.

Verá que tenemos 11 advertencias. Abordemos la advertencia de la "palabra comadreja". Vuelva al editor de texto, abra getting-started.md y elimine la palabra "exactamente".

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Guarde los cambios, confírmelos a Git y envíe la nueva versión del archivo a GitHub. Debería desencadenar la acción de GitHub .

Si hacemos clic en "Eliminó la palabra comadreja", veremos que ahora solo tenemos 10 advertencias, y la advertencia "palabra comadreja" desaparece. ¡Hurra!

Hemos terminado, y hemos cubierto mucho terreno. En esta sección tenemos:

• documentación agregada a nuestro repositorio Vale GitHub Actions,
• desencadenó la acción Vale GitHub,
• corrigió un error producido por Vale y devolvió el cambio a GitHub.

Conclusión

En un mundo que se está volviendo cada vez más remoto, es importante priorizar una buena documentación y un buen flujo de trabajo de documentación. Primero tienes que definir qué es “bueno” creando una guía de estilo. Una vez que haya descubierto las reglas de su documentación, es hora de automatizar.

La documentación debe tratarse como su base de código: un cuerpo de trabajo vivo que se itera constantemente y se vuelve un poco mejor que la última vez que lo actualizó.