Cum să automatizezi fluxul de lucru al documentației pentru dezvoltatori

Pentru a profita la maximum de acest tutorial, ar trebui să fiți familiarizat cu: Git, GitHub și Linux și cu linia de comandă.

De ce ar trebui să vă pese de documentația de înaltă calitate?

Multe echipe se luptă cu scrierea documentației . Când mergeți să verificați un cadru, documentația va fi adesea depășită sau neclară. Acest lucru poate duce la frustrare internă atunci când un membru al echipei încearcă să adauge o caracteristică, dar nu înțelege cum funcționează caracteristica actuală din cauza documentației slabe. Acest lucru poate duce la ore neproductive la locul de muncă.

Documentația slabă compromite, de asemenea, o experiență bună pentru clienți. Potrivit lui Jeff Lawson, autorul cărții Întrebați-vă dezvoltatorul și fondatorul Twilio, dacă vindeți un API ca produs, documentația este reclama supremă pentru părțile interesate tehnice . IBM a făcut un studiu despre importanța documentației, iar 90% dintre respondenți au recunoscut că și-au luat deciziile de cumpărare pe baza calității documentației unui produs.

Scrierea unei documentații bune este importantă pentru experiența dezvoltatorului și a clienților.

Dacă documentarea este atât de importantă, atunci de ce echipele de inginerie o deprioritizează?

Scrierea documentației poate scoate dezvoltatorii din „flux”. Documentația se află adesea în afara bazei de cod principal și este dificil de găsit și actualizat. Introducerea într-o foaie de calcul Excel sau într-un CMS proprietar nu este neobișnuită.

Automatizarea documentației și îmbunătățirea fluxului de lucru al documentației rezolvă acest lucru.

Automatizarea documentației de la un nivel înalt

Ce înseamnă automatizarea documentației? Înseamnă adoptarea unor practici comune de dezvoltare software. Când automatizați documentația, sunteți:

• scrierea documentației în Markdown;
• utilizarea unei pipeline de integrare continuă și implementare continuă (CI/CD) pentru a rula sarcini precum corectarea erorilor și implementarea actualizărilor (în acest tutorial, vom evidenția Acțiunile GitHub);
• implementarea instrumentelor precum Vale pentru a impune un ghid de stil și pentru a corecta greșelile gramaticale comune.

Ghidurile de stil

Înainte de a utiliza instrumente precum Vale și GitHub Actions pentru a automatiza ghidul de stil, să ne acordăm un moment pentru a defini ce este exact un ghid de stil.

Știi acel sentiment atunci când scrii documentație și ceva pare puțin neregulat? Explicațiile tale nu se potrivesc cu restul documentației, dar nu poți descrie prea bine de ce greșesc. Scrisul explică conceptul, dar nu pare să se potrivească.

Când ai acest sentiment, vocea și tonul s-ar putea să îți dispară . Rafinarea vocii și a tonului este o modalitate de a face scrisul să sune coeziv chiar dacă dezvoltați documentație care a fost editată de echipele QA, inginerie și produs. Mai jos este un exemplu de ghid de stil din aplicația de autobuz urban TAPP, preluat din cartea Strategic Writing for UX de Torrey Podmajersky.

TAPP este o aplicație de tranzit (pentru autobuze și trenuri). Antetul tabelului anunță valorile TAPP ca companie, fiind eficientă, de încredere și accesibilă. Partea stângă a tabelului listează diferitele părți acoperite de ghidul de stil: concepte, vocabular, verbozitate, gramatică și punctuație.

Împreună, acestea formează un ghid de stil . Antetul prezintă valorile, iar partea stângă a tabelului arată diferitele componente pe care le-ai găsi în orice material scris: vocabular, gramatică și punctuație. Frumusețea acestui ghid de stil este că inginerii și redactorii vor ști clar ce majuscule să folosească și ce punctuație să folosească pentru a promova identitatea mărcii Tapp.

Ghid tehnic de stil de scriere

Nu toate ghidurile de stil vin în tabele. Microsoft are un întreg site web care servește ca un ghid cuprinzător, acoperind totul, de la acronime la comunicare fără părtinire la chatbot. Desigur, Microsoft nu este singura companie care are un ghid de stil. Google are și el unul.

Problema cu ghidurile de stil

Ghidurile de stil sunt un punct de plecare excelent pentru companiile care sunt serioase în privința documentării. Ele rezolvă o mare parte a confuziei pe care dezvoltatorii o pot avea despre cum să scrie exact despre o caracteristică majoră pe care o scot.

Problema cu ghidurile de stil este că adaugă frecare procesului de scriere. Mulți scriitori, inclusiv eu, nu se obosesc să se oprească din scris și să se uite la ghidul de stil de fiecare dată când au o întrebare. Uneori, un ghid de stil este greoi și prea dificil de referit - de exemplu, Ghidul de stil Microsoft are peste o mie de pagini!

Linters și CI/CD pentru documentare

Dacă sunteți programator, atunci probabil că sunteți familiarizat cu linters. Linters sunt o modalitate ideală de a aplica standardele de codificare în echipa ta. Același lucru este valabil și cu documentația. Când creați un linter, stabiliți un etalon de calitate pentru documentația dvs. În acest tutorial, vom folosi linter-ul Vale.

Utilizarea unui fel de automatizare a documentației alături de un linter este obișnuită. Când spunem automatizare în acest context, ne referim la fluxul de lucru de integrare continuă și implementare continuă (CI/CD). CI automatizează construirea și testarea documentației . CD-ul automatizează eliberarea codului.

Puteți utiliza multe tipuri diferite de aplicații pentru a implementa un flux de lucru CI/CD. În acest tutorial, vom folosi GitHub Actions pentru a rula documentația noastră. GitHub Actions rulează CI direct într-un depozit GitHub, deci nu este nevoie să utilizați o aplicație terță parte, cum ar fi CircleCI sau Travis.

În cele din urmă, acțiunile GitHub sunt bazate pe evenimente , ceea ce înseamnă că sunt declanșate atunci când se întâmplă ceva, cum ar fi atunci când cineva scrie o cerere de extragere sau o problemă. În exemplul nostru, o acțiune GitHub va avea loc atunci când cineva împinge modificări în ramura sa principală.

Acțiuni GitHub

Mai întâi, creați un depozit GitHub. Apoi, local, creați un folder și cd în el.

 mkdir automated-docs cd automated-docs

Odată ce vă aflați în folder, inițializați directorul pentru Git.

 git init

După ce ați inițializat depozitul, continuați să creați un director de flux de lucru în folderul dvs.

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

Fluxurile de lucru sunt locul în care vom stoca toate acțiunile noastre GitHub. După ce ați creat un dosar workflows de lucru, creați un nou flux de lucru. Vom numi acest flux de lucru vale.yml .

 touch vale.yml

Vale.yml este un fișier YAML. În acest fișier de flux de lucru, vom include acțiuni și locuri de muncă.

Acum, deschide vale.yml în editorul tău de text preferat.

 nano vale.yml

Copiați și lipiți următoarele în vale.yml și să trecem peste context și sintaxă.

 # 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
  Acesta este numele sau ceea ce numim fluxul nostru de lucru. Este o sfoară.
• on
  Aceasta controlează fluxul de lucru și declanșatoarele.
• jobs
  Aici ne stabilim și ne controlăm acțiunile. Selectăm mediul în care se vor desfășura acțiunile noastre - de obicei este un pariu bun să mergeți cu Ubuntu. Și aici vom adăuga acțiunile noastre.

GitHub are un ghid pentru toate celelalte sintaxe și variabile ale fluxului de lucru, în cazul în care sunteți curios.

În această secțiune, avem:

• a învățat ce sunt acțiunile GitHub,
• am creat primul nostru flux de lucru GitHub,
• a identificat cele mai importante părți ale unui fișier YAML al fluxului de lucru GitHub.

În continuare, vom personaliza fluxul de lucru GitHub pentru a folosi Vale.

Configurați Vale în fișierul de acțiuni GitHub

După ce am copiat fișierul flux de lucru de bază, este timpul să-l personalizăm, astfel încât să putem începe să folosim acțiunile Vale. Primul lucru de făcut este să schimbați numele fișierului YAML în Docs-Linting .

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

În continuare, dorim să rulăm testul Vale odată ce cineva a introdus modificările în ramura principală de pe GitHub. Nu dorim ca testul să ruleze atunci când cineva creează o cerere de extragere, așa că vom șterge acea parte a fișierului YAML.

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

Secțiunea de jobs este partea principală a fișierului fluxului de lucru și este responsabilă pentru rularea acțiunilor GitHub.

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

Aceste acțiuni vor rula pe cea mai recentă versiune de Ubuntu. Acțiunea Checkout verifică depozitul pentru ca fluxul de lucru GitHub să îl acceseze.

Acum este timpul să adăugați o acțiune Vale la fluxul nostru de lucru 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}}

Ne-am numit acțiunea Vale . Variabila uses arată ce versiune de Vale vom implementa - în mod ideal, ar trebui să folosim cea mai recentă versiune. În variabila with , setăm debug la true .

Secțiunea de styles ne oferă opțiunea de a adăuga un ghid de stil la Vale. În acest exemplu, vom folosi write-good și ghidul de stil oficial al Microsoft. Rețineți că putem folosi și alte ghiduri de stil.

Partea finală a acestei acțiuni GitHub este env . Pentru a rula această acțiune GitHub, trebuie să includem un token secret.

Iată cum ar trebui să arate rezultatul:

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

După ce ați terminat de făcut modificări, salvați fișierul, trimiteți-vă în Git și trimiteți modificările în GitHub.

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

Pentru a recapitula, în această secțiune, avem:

• a declanșat acțiunea să apară atunci când împingem cod nou în ramura main ;
• a adăugat o acțiune Vale, setând debug la true și identificând ghidurile de stil;
• a adăugat un token GitHub;
• a comis modificări și a trimis la GitHub.

În secțiunea următoare, vom crea un fișier de configurare Vale.

Configurarea fișierului de configurare Vale

Accesați rădăcina directorului proiectului dvs., apoi touch .vale.ini . Deschideți .vale.ini într-un editor de text. Copiați și lipiți următoarele în .vale.ini :

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

• StylesPath = .github/styles
StylesPath oferă calea stilurilor Vale.
• MinAlertLevel = warning
  Nivelul minim de alertă arată gradul de severitate al alertelor. Opțiunile sunt suggestion , warning și error .
• [formats]
Markdown = markdown setează formatul ca Markdown.
• [*.md]
  Configurația BasedOnStyles = write-good, Microsoft va rula write-good și ghidul de stil Microsoft pe toate fișierele Markdown care se termină cu .md .

Această configurație este strictul minim. Dacă sunteți interesat să aflați mai multe despre configurarea Vale, mergeți la documentație.

Când ați terminat de făcut modificări, salvați fișierul și comiteți și împingeți în GitHub.

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

În această parte, am învățat elementele interne ale unui fișier de configurare Vale. Acum este timpul să creați o documentație de probă.

Crearea documentației și declanșarea acțiunilor Vale GitHub

Acum este timpul să vedeți Vale și GitHub Actions în acțiune! Vom crea un fișier Markdown și îl umplem cu text. Și vom primi textul nostru de la DeLorean Ipsum.

Accesați rădăcina proiectului dvs., apoi touch getting-started.md . După ce ați creat fișierul getting-started , accesați DeLorean Ipsum și creați un text simulat pentru documentația dvs. Apoi, reveniți la editorul de text și inserați textul în 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ți fișierul, confirmați-l și împingeți-l în GitHub.

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

După ce ați introdus modificările, mergeți la GitHub unde se află depozitul dvs. Accesați fila Actions .

Veți vedea toate fluxurile de lucru în partea stângă. Avem doar unul, numit Docs-Linting , același nume pe care l-am pus în fișierul vale.yml .

Când împingem documentația către GitHub, vom declanșa acțiunea.

Dacă acțiunea s-a desfășurat fără probleme, vom primi o bifă verde.

Faceți clic pe „Documente adăugate” pentru a obține un raport complet.

Veți vedea că avem 11 avertismente. Să ne ocupăm de avertismentul „cuvânt nevăstuică”. Reveniți la editorul de text, deschideți getting-started.md și ștergeți cuvântul „exact”.

 # 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ți modificările, trimiteți-le în Git și împingeți noua versiune a fișierului în GitHub. Ar trebui să declanșeze acțiunea GitHub .

Dacă facem clic pe „Șterge cuvântul nevăstuică”, vom vedea că avem doar 10 avertismente acum, iar avertismentul „cuvânt nevăstuică” a dispărut. Ura!

Am terminat și am parcurs mult teren. În această secțiune, avem:

• a adăugat documentație la depozitul nostru de acțiuni Vale GitHub,
• a declanșat acțiunea Vale GitHub,
• a corectat o eroare produsă de Vale și a împins modificarea înapoi în GitHub.

Concluzie

Într-o lume care devine din ce în ce mai îndepărtată, este important să acordați prioritate unei documentații bune și al fluxului de lucru al documentării. Mai întâi trebuie să definiți ce este „bun” prin crearea unui ghid de stil. Odată ce v-ați dat seama de regulile documentației, atunci este timpul să vă automatizați.

Documentația ar trebui tratată ca baza dvs. de cod: un corp de lucru viu care este în mod constant repetat și devine puțin mai bun decât ultima dată când ați actualizat-o.