Come automatizzare il flusso di lavoro della documentazione per gli sviluppatori

Per ottenere il massimo da questo tutorial, dovresti avere familiarità con: Git, GitHub e Linux e la riga di comando.

Perché dovresti preoccuparti della documentazione di alta qualità?

Molti team hanno difficoltà a scrivere la documentazione . Quando vai a controllare un framework, la documentazione sarà spesso obsoleta o poco chiara. Ciò può portare a frustrazione interna quando un membro del team tenta di aggiungere una funzionalità, ma non capisce come funziona la funzionalità corrente a causa della scarsa documentazione. Questo può portare a ore improduttive sul lavoro.

Una scarsa documentazione compromette anche una buona esperienza del cliente. Secondo Jeff Lawson, autore di Ask Your Developer e fondatore di Twilio, se vendi un'API come prodotto, la documentazione è la pubblicità definitiva per gli stakeholder tecnici . IBM ha condotto uno studio sull'importanza della documentazione e il 90% degli intervistati ha ammesso di aver preso le proprie decisioni di acquisto in base alla qualità della documentazione di un prodotto.

Scrivere una buona documentazione è importante per le esperienze degli sviluppatori e dei clienti.

Se la documentazione è così importante, allora perché i team di ingegneri la svalutano?

Scrivere documentazione può far uscire gli sviluppatori dal "flusso". La documentazione spesso risiede al di fuori della base di codice principale ed è difficile da trovare e aggiornare. Non è raro inserirlo in un foglio di calcolo Excel o in un CMS proprietario.

L'automazione della documentazione e il miglioramento del flusso di lavoro della documentazione risolve questo problema.

Automatizzare la documentazione da un livello elevato

Cosa significa automatizzare la documentazione? Significa adottare pratiche comuni di sviluppo software. Quando automatizzi la documentazione, sei:

• scrivere la tua documentazione in Markdown;
• utilizzando una pipeline di integrazione continua e distribuzione continua (CI/CD) per eseguire attività come la correzione di errori e la distribuzione di aggiornamenti (in questo tutorial evidenzieremo le azioni di GitHub);
• implementare strumenti come Vale per imporre una guida di stile e correggere errori grammaticali comuni.

Le guide di stile

Prima di utilizzare strumenti come Vale e GitHub Actions per automatizzare la guida di stile, prendiamoci un momento per definire cos'è esattamente una guida di stile.

Hai presente quella sensazione quando scrivi documentazione e qualcosa ti sembra un po' strano? Le tue spiegazioni non si adattano al resto della documentazione, ma non puoi descrivere del tutto il motivo per cui sono sbagliate. La scritta spiega il concetto, ma non sembra adattarsi.

Quando provi questa sensazione, la tua voce e il tuo tono potrebbero essere spenti . Perfezionare la voce e il tono è un modo per rendere la scrittura coerente anche se si sta sviluppando la documentazione che è stata modificata dal team di controllo qualità, ingegneria e prodotto. Di seguito è riportato un esempio di guida di stile dall'applicazione per autobus urbani TAPP, tratta dal libro Strategic Writing for UX di Torrey Podmajersky.

TAPP è un'applicazione di transito (per autobus e treni). L'intestazione della tabella annuncia i valori di TAPP come azienda, essendo efficiente, affidabile e accessibile. Il lato sinistro della tabella elenca le diverse parti trattate dalla guida di stile: concetti, vocabolario, verbosità, grammatica e punteggiatura.

Insieme, questi fanno una guida di stile . L'intestazione introduce i valori e il lato sinistro della tabella mostra i diversi componenti che potresti trovare in qualsiasi materiale scritto: vocabolario, grammatica e punteggiatura. Il bello di questa guida di stile è che ingegneri e copywriter sapranno chiaramente quale maiuscolo usare e quale punteggiatura usare per promuovere l'identità del marchio Tapp.

Guida tecnica allo stile di scrittura

Non tutte le guide di stile sono disponibili nelle tabelle. Microsoft ha un intero sito Web che funge da guida completa, che copre tutto, dagli acronimi alla comunicazione senza pregiudizi ai chatbot. Microsoft ovviamente non è l'unica azienda che ha una guida di stile. Anche Google ne ha uno.

Il problema con le guide di stile

Le guide di stile sono un ottimo punto di partenza per le aziende che prendono sul serio la documentazione. Risolvono gran parte della confusione che gli sviluppatori potrebbero avere su come scrivere esattamente su una caratteristica importante che stanno eliminando.

Il problema con le guide di stile è che aggiungono attrito al processo di scrittura. Molti scrittori, me compreso, non si preoccupano di smettere di scrivere e di guardare la guida di stile ogni volta che hanno una domanda. A volte, una guida di stile è ingombrante e troppo difficile da consultare, ad esempio la Guida di stile di Microsoft è lunga più di mille pagine!

Linters e CI/CD per la documentazione

Se sei un programmatore, probabilmente hai familiarità con i linters. I linter sono un modo ideale per imporre standard di codifica alla tua squadra. Lo stesso vale per la documentazione. Quando crei un linter, stai impostando un benchmark di qualità per la tua documentazione. In questo tutorial useremo la linter di Vale.

L'uso di una sorta di automazione della documentazione insieme a un linter è comune. Quando diciamo automazione in questo contesto, ci riferiamo al flusso di lavoro di integrazione continua e distribuzione continua (CI/CD). CI automatizza la creazione e il test della documentazione . Il CD automatizza il rilascio del codice.

Puoi utilizzare diversi tipi di app per implementare un flusso di lavoro CI/CD. In questo tutorial, useremo GitHub Actions per eseguire il nostro linter di documentazione. GitHub Actions esegue CI direttamente in un repository GitHub, quindi non è necessario utilizzare un'applicazione di terze parti, come CircleCI o Travis.

Infine, le azioni GitHub sono basate sugli eventi , il che significa che vengono attivate quando succede qualcosa, ad esempio quando qualcuno scrive una richiesta pull o un problema. Nel nostro esempio, si verificherà un'azione GitHub quando qualcuno invia le modifiche al proprio ramo principale.

Azioni GitHub

Innanzitutto, crea un repository GitHub. Quindi, localmente, crea una cartella e cd in essa.

 mkdir automated-docs cd automated-docs

Una volta che sei nella cartella, inizializza la directory per Git.

 git init

Dopo aver inizializzato il repository, procedi alla creazione di una directory del flusso di lavoro nella tua cartella.

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

I flussi di lavoro sono il luogo in cui memorizzeremo tutte le nostre azioni GitHub. Dopo aver creato una cartella workflows di lavoro, crea un nuovo flusso di lavoro. Chiameremo questo flusso di lavoro vale.yml .

 touch vale.yml

Vale.yml è un file YAML. In questo file di flusso di lavoro, includeremo azioni e lavori.

Ora apri vale.yml nel tuo editor di testo preferito.

 nano vale.yml

Copia e incolla quanto segue in vale.yml e esaminiamo il contesto e la sintassi.

 # 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
  Questo è il nome, o quello che chiamiamo il nostro flusso di lavoro. È una stringa.
• on
  Questo controlla il flusso di lavoro e i trigger.
• jobs
  È qui che impostiamo e controlliamo le nostre azioni. Selezioniamo l'ambiente in cui verranno eseguite le nostre azioni: di solito è una buona scommessa andare con Ubuntu. Ed è qui che aggiungeremo le nostre azioni.

GitHub ha una guida su tutte le altre sintassi e variabili del flusso di lavoro, nel caso tu sia curioso.

In questa sezione abbiamo:

• imparato cosa sono le azioni GitHub,
• creato il nostro primo flusso di lavoro GitHub,
• identificato le parti più importanti di un file YAML del flusso di lavoro GitHub.

Successivamente, personalizzeremo il nostro flusso di lavoro GitHub per utilizzare Vale.

Configura Vale nel file delle azioni di GitHub

Dopo aver copiato il file del flusso di lavoro di base, è il momento di personalizzarlo, in modo da poter iniziare a utilizzare le azioni Vale. La prima cosa da fare è cambiare il nome del file YAML in Docs-Linting .

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

Successivamente, vogliamo eseguire il test Vale una volta che qualcuno ha inviato le modifiche al ramo principale su GitHub. Non vogliamo che il test venga eseguito quando qualcuno crea una richiesta pull, quindi elimineremo quella parte del file YAML.

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

La sezione dei jobs è la parte principale del file del flusso di lavoro ed è responsabile dell'esecuzione delle azioni GitHub.

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

Queste azioni verranno eseguite sull'ultima versione di Ubuntu. L'azione Checkout estrae il repository in modo che il flusso di lavoro GitHub possa accedervi.

Ora è il momento di aggiungere un'azione Vale al nostro flusso di lavoro 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}}

Abbiamo chiamato la nostra azione Vale . La variabile uses mostra quale versione di Vale implementeremo — idealmente, dovremmo usare la versione più recente. Nella variabile with , impostiamo il debug su true .

La sezione styles ci dà la possibilità di aggiungere una guida di stile a Vale. In questo esempio, useremo write-good e la guida di stile ufficiale di Microsoft. Tieni presente che possiamo utilizzare anche altre guide di stile.

La parte finale di questa azione GitHub è env . Per eseguire questa azione GitHub, dobbiamo includere un token segreto.

Ecco come dovrebbe essere il risultato:

 # 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 volta terminate le modifiche, salva il file, esegui il commit su Git e invia le modifiche a GitHub.

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

Ricapitolando, in questa sezione abbiamo:

• attivato l'azione che si verifica quando inseriamo il nuovo codice nel ramo main ;
• aggiunta un'azione Vale, impostando il debug su true e identificando le guide di stile;
• aggiunto un token GitHub;
• modifiche apportate e inviate a GitHub.

Nella prossima sezione creeremo un file di configurazione Vale.

Configurazione del file di configurazione Vale

Vai alla radice della directory del tuo progetto, quindi touch .vale.ini . Apri .vale.ini in un editor di testo. Copia e incolla quanto segue in .vale.ini :

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

• StylesPath = .github/styles
StylesPath fornisce il percorso degli stili Vale.
• MinAlertLevel = warning
  Il livello di avviso minimo mostra la scala di gravità negli avvisi. Le opzioni sono suggestion , warning ed error .
• [formats]
Markdown = markdown imposta il formato come Markdown.
• [*.md]
  La configurazione BasedOnStyles = write-good, Microsoft eseguirà write-good e la guida di stile Microsoft su tutti i file Markdown che terminano con .md .

Questa configurazione è il minimo indispensabile. Se sei interessato a saperne di più sulla configurazione di Vale, vai alla documentazione.

Quando hai finito di apportare modifiche, salva il file, esegui il commit e invialo a GitHub.

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

In questa parte, abbiamo appreso gli interni di un file di configurazione Vale. Ora è il momento di creare una documentazione di esempio.

Creazione di documentazione e attivazione delle azioni Vale GitHub

Ora è il momento di vedere Vale e GitHub Actions in azione! Creeremo un file Markdown e lo riempiremo di testo. E riceveremo il nostro testo da DeLorean Ipsum.

Vai alla radice del tuo progetto, quindi touch getting-started.md . Dopo getting-started creato il file introduttivo, vai su DeLorean Ipsum e crea del testo fittizio per la tua documentazione. Quindi, torna al tuo editor di testo e incolla il testo in 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?

Salva il file, esegui il commit e invialo a GitHub.

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

Dopo aver eseguito il push delle modifiche, vai su GitHub dove si trova il tuo repository. Vai alla scheda Actions .

Vedrai tutti i tuoi flussi di lavoro sul lato sinistro. Ne abbiamo solo uno, chiamato Docs-Linting , lo stesso nome che abbiamo inserito nel file vale.yml .

Quando inviamo la documentazione su GitHub, attiveremo l'azione.

Se l'azione è stata eseguita senza problemi, verrà visualizzato un segno di spunta verde.

Fare clic su "Documenti aggiunti" per ottenere un rapporto completo.

Vedrai che abbiamo ricevuto 11 avvisi. Affrontiamo l'avvertimento della "parola donnola". Torna all'editor di testo, apri getting-started.md ed elimina la parola "esattamente".

 # 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?

Salva le modifiche, esegui il commit su Git e invia la nuova versione del file a GitHub. Dovrebbe attivare l'azione GitHub .

Se facciamo clic su "Eliminato la parola donnola", vedremo che ora abbiamo solo 10 avvisi e l'avviso "parola donnola" è sparito. Evviva!

Abbiamo finito e abbiamo percorso molto terreno. In questa sezione abbiamo:

• aggiunta documentazione al nostro repository Vale GitHub Actions,
• ha attivato l'azione Vale GitHub,
• corretto un errore prodotto da Vale e rinviato la modifica a GitHub.

Conclusione

In un mondo che sta diventando sempre più remoto, è importante dare la priorità a una buona documentazione e a un buon flusso di lavoro della documentazione. Devi prima definire cosa sia "buono" creando una guida di stile. Una volta che hai capito le regole della tua documentazione, allora è il momento di automatizzare.

La documentazione dovrebbe essere trattata come la tua base di codice: un corpo di lavoro vivente che viene costantemente ripetuto e diventa un po' migliore rispetto all'ultima volta che lo hai aggiornato.