Comment automatiser le flux de travail de documentation pour les développeurs

Pour tirer le meilleur parti de ce tutoriel, vous devez être familiarisé avec : GitGitHub et Linux et la ligne de commande.

Pourquoi ? Devriez-vous vous soucier d'une documentation de haute qualité ?

De nombreuses équipes ont du mal à écrire de la documentation. Lorsque vous allez vérifier un framework, la documentation sera souvent obsolète ou peu claire. Cela peut entraîner une frustration interne lorsqu'un membre de l'équipe essaie d'ajouter une fonctionnalité, mais qu'il ne comprend pas comment la fonctionnalité actuelle fonctionne en raison d'une mauvaise documentation. Cela peut entraîner des heures de travail improductives.

Une mauvaise documentation compromet également une bonne expérience client. Selon Jeff Lawson, auteur de Ask Your Developer et fondateur de Twilio, si vous vendez une API en tant que produit, la documentation est la publicité ultime pour les parties prenantes techniques. IBM a réalisé une étude sur l'importance de la documentation, et 90 % des personnes interrogées ont admis qu'elles prenaient leurs décisions d'achat en fonction de la qualité de la documentation d'un produit.

La rédaction d'une bonne documentation est importante pour le développeur et l'expérience client.

Si La documentation est si importante, alors pourquoi les équipes d'ingénierie la dépriorisent-elles ?

La rédaction de la documentation peut faire sortir les développeurs du « flux ». La documentation réside souvent en dehors de la base de code principale et elle est difficile à trouver et à mettre à jour. Le mettre dans une feuille de calcul Excel ou un CMS propriétaire n'est pas rare.

L'automatisation de la documentation et l'amélioration du flux de travail de la documentation résolvent ce problème. Cela signifie adopter des pratiques communes de développement de logiciels. Lorsque vous automatisez la documentation, vous :

• écrivez votre documentation dans Markdown ;
• utilisez un pipeline d'intégration continue et de déploiement continu (CI/CD) pour exécuter des tâches telles que la correction d'erreurs et le déploiement de mises à jour (dans ce didacticiel, nous va mettre en évidence les actions GitHub);
• mettre en œuvre des outils comme Vale pour appliquer un guide de style et corriger les erreurs grammaticales courantes.

Les guides de style

Avant d'utiliser des outils tels que Vale et GitHub Actions pour automatiser le guide de style, prenons un moment pour définir ce qu'est exactement un guide de style. Vos explications ne correspondent pas au reste de la documentation, mais vous ne pouvez pas vraiment décrire pourquoi elles ont tort. L'écriture explique le concept, mais cela ne semble pas correspondre. Le raffinement de la voix et du ton est un moyen de rendre l'écriture cohérente même si vous développez une documentation qui a été éditée par les équipes d'assurance qualité, d'ingénierie et de produit. Vous trouverez ci-dessous un exemple de guide de style de l'application de bus urbain TAPP, tiré du livre Strategic Writing for UX de Torrey Podmajersky.

TAPP est une application de transport en commun (pour les bus et les trains). L'en-tête du tableau annonce les valeurs de TAPP en tant qu'entreprise, efficace, digne de confiance et accessible. Le côté gauche du tableau répertorie les différentes parties couvertes par le guide de style : concepts, vocabulaire, verbosité, grammaire et ponctuation.

Ensemble, ils constituent un guide de style. L'en-tête présente les valeurs et le côté gauche du tableau montre les différents composants que vous trouverez dans tout document écrit : vocabulaire, grammaire et ponctuation. La beauté de ce guide de style est que les ingénieurs et les rédacteurs sauront clairement quelle majuscule utiliser et quelle ponctuation utiliser pour promouvoir l'identité de la marque Tapp.

Technical Writing Style Guide

Tous les guides de style ne sont pas fournis sous forme de tableaux. Microsoft dispose d'un site Web complet qui sert de guide complet, couvrant tout, des acronymes à la communication sans parti pris en passant par les chatbots. Microsoft n'est bien sûr pas la seule entreprise à avoir un guide de style. Google en a un aussi.

Les guides de style Trouble With Style

Les guides de style sont un excellent point de départ pour les entreprises qui prennent la documentation au sérieux. Ils résolvent une grande partie de la confusion que les développeurs pourraient avoir sur la manière exacte d'écrire sur une fonctionnalité majeure qu'ils mettent en avant.

Le problème avec les guides de style est qu'ils ajoutent de la friction au processus d'écriture. De nombreux écrivains, dont moi, ne prennent pas la peine d'arrêter d'écrire et de consulter le guide de style chaque fois qu'ils ont une question. Parfois, un guide de style est encombrant et trop difficile à référencer — par exemple, le Microsoft Style Guide fait plus de mille pages !

Linters et CI/CD pour la documentation

Si vous êtes un programmeur, alors vous êtes probablement familier avec les linters. Les linters sont un moyen idéal pour appliquer les normes de codage à votre équipe. Il en est de même avec la documentation. Lorsque vous créez un linter, vous définissez une référence de qualité pour votre documentation. Dans ce tutoriel, nous allons utiliser le Vale linter.

L'utilisation d'une sorte d'automatisation de la documentation avec un linter est courante. Lorsque nous parlons d'automatisation dans ce contexte, nous faisons référence au workflow d'intégration continue et de déploiement continu (CI/CD). CI automatise la construction et le test de la documentation. Le CD automatise la publication du code.

Vous pouvez utiliser de nombreux types d'applications pour mettre en œuvre un flux de travail CI/CD. Dans ce tutoriel, nous allons utiliser les actions GitHub pour exécuter notre linter de documentation. Les actions GitHub exécutent CI directement dans un référentiel GitHub, il n'est donc pas nécessaire d'utiliser une application tierce, telle que CircleCI ou Travis.

Enfin, les actions GitHub sont pilotées par les événementsce qui signifie qu'elles sont déclenchés lorsque quelque chose se produit, par exemple lorsque quelqu'un écrit une demande d'extraction ou un problème. Dans notre exemple, une action GitHub se produit lorsque quelqu'un envoie des modifications à sa branche principale.

Actions GitHub

Tout d'abord, créez un dépôt GitHub. Ensuite, localement, créez un dossier et cd dedans.

mkdir automatic-docs
cd automatic-docs

Une fois que vous êtes dans le dossier, initialisez le répertoire pour Git.

git init

Une fois que vous avez initialisé le référentiel, créez un répertoire de workflow dans votre dossier.

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

Les workflows sont l'endroit où nous stockerons toutes nos actions GitHub. Une fois que vous avez créé un dossier workflowscréez un nouveau workflow. Nous allons nommer ce workflow vale.yml.

touch vale.yml

Vale.yml est un fichier YAML. Dans ce fichier de workflow, nous inclurons les actions et les tâches.

Maintenant, ouvrez vale.yml dans votre éditeur de texte préféré.

nano vale.yml

Copiez et collez ce qui suit dans vale.ymlet passons en revue le contexte et la syntaxe.

# Il s'agit d'un workflow de base pour vous aider à démarrer avec Actions.

nom : CI

# Contrôle quand le workflow s'exécutera
au:
  # Déclenche le workflow sur les événements push ou pull request mais uniquement pour la branche principale
  pousser:
    succursales : [ main ]
  pull_request :
    succursales : [ main ]

  # Vous permet d'exécuter ce workflow manuellement à partir de l'onglet Actions
  workflow_dispatch :

# Une exécution de workflow est composée d'un ou plusieurs travaux qui peuvent s'exécuter séquentiellement ou en parallèle
travaux:
  # Ce workflow contient un seul travail appelé "build"
  construire:
    # Le type de coureur sur lequel le travail sera exécuté
    run-on: ubuntu-latest

    # Les étapes représentent une séquence de tâches qui seront exécutées dans le cadre du travail
    pas:
      # Extrait votre référentiel sous $GITHUB_WORKSPACE, afin que votre travail puisse y accéder
      - utilise : actions/checkout@v2

      # Exécute une seule commande à l'aide du shell runners
      - name : Exécute un script d'une ligne
        run : echo Bonjour tout le monde !

      # Exécute un ensemble de commandes à l'aide du shell runners
      - name : Exécute un script multi-lignes
        exécuter : |
          echo Ajouter d'autres actions à construire,
          echo test et déployez votre projet.
        env :
          GITHUB_TOKEN : ${{secrets.GITHUB_TOKEN}}

• name
  C'est le nom, ou ce que nous appelons notre flux de travail. C'est une chaîne.
• on
  Ceci contrôle le workflow et les déclencheurs.
• jobs
  C'est ici que nous configurons et contrôlons nos actions. Nous sélectionnons l'environnement dans lequel nos actions seront exécutées – c'est généralement un bon pari d'aller avec Ubuntu. Et c'est là que nous ajouterons nos actions.

GitHub a un guide sur tous les autres flux de travail syntaxe et variablesau cas où vous seriez curieux.

Dans cette section, nous avons :

• a appris ce que sont les actions GitHub,
• a créé notre premier workflow GitHub,
• a identifié les parties les plus importantes d'un fichier YAML de workflow GitHub.

Ensuite, nous allons personnaliser notre workflow GitHub pour utiliser Vale.

Configurer Vale dans le fichier d'actions GitHub

Une fois que nous avons copié le fichier de workflow de base, il est temps de le personnaliser, afin que nous puissions commencer à utiliser les actions Vale. La première chose à faire est de changer le nom du fichier YAML en Docs-Linting.

# Il s'agit d'un workflow de base pour vous aider à démarrer avec Actions.

name: Docs-Linting

Ensuite, nous voulons exécuter le test Vale une fois que quelqu'un a poussé ses modifications vers la branche principale sur GitHub. Nous ne voulons pas que le test s'exécute lorsque quelqu'un crée une demande d'extraction, nous allons donc supprimer cette partie du fichier YAML.

 sur :
  # Déclenche le workflow sur les événements push ou pull request mais uniquement pour la branche principale
  pousser:
    succursales : [ main ]

La section jobs est la partie principale du fichier de workflow, et elle est responsable de l'exécution des actions GitHub.

jobs :
  construire:
    run-on: ubuntu-latest
    pas:
    - nom : Caisse
      utilise : actions/checkout@master

Ces actions vont s'exécuter sur la dernière version d'Ubuntu. L'action Checkout extrait le référentiel pour que le workflow GitHub y accède.

Il est maintenant temps d'ajouter une action Vale à notre workflow GitHub.

 - nom : Vale
      utilise : errata-ai/vale-action@v1.4.2
      avec:
        débogage : vrai
        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}}

Nous avons nommé notre action Vale. La variable uses indique quelle version de Vale nous allons implémenter — idéalement, nous devrions utiliser la version la plus récente. Dans la variable withnous définissons debug sur true.

La section styles nous donne la possibilité d'ajouter un guide de style à Vale. Dans cet exemple, nous allons utiliser write-good et le guide de style officiel de Microsoft. Gardez à l'esprit que nous pouvons également utiliser d'autres guides de style.

La dernière partie de cette action GitHub est env. Afin d'exécuter cette action GitHub, nous devons inclure un jeton secret.

Voici à quoi devrait ressembler le résultat :

# Ceci est un flux de travail de base pour vous aider à démarrer avec les actions .

nom : Docs-Linting

# Contrôle quand l'action sera exécutée.
au:
  # Déclenche le workflow sur les événements push ou pull request mais uniquement pour la branche principale
  pousser:
    succursales : [ main ]

  # Vous permet d'exécuter ce workflow manuellement à partir de l'onglet Actions
  workflow_dispatch :

travaux:
  prose:
    run-on: ubuntu-latest
    pas:
    - nom : Caisse
      utilise : actions/checkout@master

    - nom : Vale
      utilise : errata-ai/vale-action@v1.4.2
      avec:
        débogage : vrai
        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}}

Une fois les modifications terminées, enregistrez le fichier, validez dans Git et transférez vos modifications sur GitHub.

git add .github/workflows/vale.yml
git commit -m "Ajout du référentiel github au projet"
git push -u origin main

Pour récapituler, dans cette section, nous avons :

• déclenché l'action pour qu'elle se produise lorsque nous transmettons un nouveau code à la branche main ;
• ajouté une action Vale , en définissant debug sur true et en identifiant les guides de style ;
• ajout d'un jeton GitHub ;
• modifications validées et poussées vers GitHub.

Dans la section suivante, nous allons allez créer un fichier de configuration Vale.

Configuration du fichier de configuration Vale

Allez à la racine du répertoire de votre projet, puis touchez .vale.ini. Ouvrez .vale.ini dans un éditeur de texte. Copiez et collez ce qui suit dans .vale.ini :

StylesPath = .github/styles
MinAlertLevel = avertissement

[formats]
démarque = démarque

[*.md]
BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
  Le StylesPath donne le chemin des styles Vale.
• MinAlertLevel = warning
  L'alerte minimale level affiche l'échelle de gravité des alertes. Les options sont suggestionwarning et error.
• [formats]
Markdown = markdown ensembles le format comme Markdown.
• [*.md]
  La configuration BasedOnStyles = write-good, Microsoft exécutera write-good et le guide de style Microsoft sur tous les fichiers Markdown se terminant par .md.

Cette configuration est le strict minimum. Si vous souhaitez en savoir plus sur la configuration de Vale, rendez-vous sur la documentation.

Lorsque vous avez terminé d'apporter des modifications, enregistrez le fichier, validez et envoyez à GitHub.

git add . vale.ini
git commit -m "Ajout du fichier de configuration Vale"
git push -u origin main

Dans cette partie, nous avons appris les rouages ​​d'un fichier de configuration Vale. Il est maintenant temps de créer un exemple de documentation.

Création de documentation et déclenchement des actions Vale GitHub

Il est maintenant temps de voir les actions Vale et GitHub en action ! Nous allons créer un fichier Markdown et le remplir de texte. Et nous allons obtenir notre texte de DeLorean Ipsum.

Allez à la racine de votre projet, puis touchez Getting-started.md. Une fois que vous avez créé le fichier getting-startedaccédez à DeLorean Ipsum et créez un texte factice pour votre documentation. Ensuite, revenez à votre éditeur de texte et collez le texte dans getting-started-md.

# Guide de démarrage

Je ne peux pas jouer. C'est mon père. Ils sont en retard. Mon expérience a fonctionné. Ils ont tous exactement vingt-cinq minutes de retard. Marty, cela peut sembler un peu avant-gardiste, mais je me demandais si tu pouvais m'inviter à l'Enchantment Under The Sea Dance samedi. Eh bien, ce sont vos parents, vous devez les connaître. Quels sont leurs intérêts communs, qu'aiment-ils faire ensemble ?

D'accord. Est-ce que ça va? Waouh, attendez, Doc. Quoi, tu veux dire comme un rencard ? Je ne veux plus te revoir ici.

Non, Biff, tu la laisses tranquille. Jésus, George, c'est un miracle que je sois jamais né. Hé, hé, continue de rouler, continue de rouler là. Non, non, non, non, cette ventouse est électrique. Mais j'ai besoin d'une réaction nucléaire pour générer les un virgule vingt et un gigawatts d'électricité dont j'ai besoin. Je l'ai pris dans la cave à liqueur de la vieille dame. Vous connaissez Marty, vous m'avez l'air si familier, est-ce que je connais votre mère ? 

Enregistrez le fichier, validez-le et transférez-le sur GitHub.

 git add Getting-started.md
git commit -m "premier brouillon"
git push -u origin main 

Une fois que vous avez poussé les modifications, rendez-vous sur GitHub où se trouve votre référentiel. Accédez à l'onglet Actions.

Vous verrez tous vos flux de travail sur le côté gauche. Nous n'en avons qu'un, nommé Docs-Lintingle même nom que nous avons mis dans le fichier vale.yml.

Lorsque nous transmettons la documentation à GitHub, nous déclenchons l'action.

Si l'action s'est déroulée sans problème, nous obtiendrons une coche verte.

Cliquez sur « Documents ajoutés » pour obtenir un rapport complet.

Vous verrez que nous avons reçu 11 avertissements. Parlons de l'avertissement "mot belette". Revenez à l'éditeur de texte, ouvrez getting-started.md et supprimez le mot « exactement ».

# Guide de démarrage

Je ne peux pas jouer. C'est mon père. Ils sont en retard. Mon expérience a fonctionné. Ils sont tous lents de vingt-cinq minutes. Marty, cela peut sembler un peu avant-gardiste, mais je me demandais si vous voudriez m'inviter à l'Enchantment Under The Sea Dance samedi. Eh bien, ce sont vos parents, vous devez les connaître. Quels sont leurs intérêts communs, qu'aiment-ils faire ensemble ?

D'accord. Est-ce que ça va? Waouh, attendez, Doc. Quoi, tu veux dire comme un rencard ? Je ne veux plus te revoir ici.

Non, Biff, tu la laisses tranquille. Jésus, George, c'est un miracle que je sois jamais né. Hé, hé, continue de rouler, continue de rouler là-bas. Non, non, non, non, cette ventouse est électrique. Mais j'ai besoin d'une réaction nucléaire pour générer les un virgule vingt et un gigawatts d'électricité dont j'ai besoin. Je l'ai pris dans la cave à liqueur de la vieille dame. Vous connaissez Marty, vous m'avez l'air si familier, est-ce que je connais votre mère ? 

Enregistrez les modifications, validez-les dans Git et transférez la nouvelle version du fichier sur GitHub. Il devrait déclencher l'action GitHub.

Si nous cliquons sur « Supprimé le mot de la fouine », nous verrons que nous n'avons plus que 10 avertissements maintenant, et l'avertissement « mot de la fouine » a disparu. Hourra !

Nous avons terminé et nous avons parcouru beaucoup de chemin. Dans cette section, nous avons :

• ajouté de la documentation à notre référentiel Vale GitHub Actions,
• déclenché l'action Vale GitHub,
• corrigé une erreur produite par Vale et renvoyé la modification vers GitHub.

Conclusion[19659004]Dans un monde de plus en plus éloigné, il est important de donner la priorité à une bonne documentation et à un bon workflow de documentation. Vous devez d'abord définir ce qu'est le « bien » en créant un guide de style. Une fois que vous avez compris les règles de votre documentation, il est temps d'automatiser.

La documentation doit être traitée comme votre base de code : un corps de travail vivant qui est constamment itéré et devient un peu meilleur que la dernière fois que vous l'a mis à jour.

(yk, al)