Kuidas hoida dokumentatsioon ajakohasena, kui annad iga nädal midagi välja

autor: Fraser Hardy

Ühendatud pull request punaste ja roheliste diffi ridadega ning nool, mis voolab abiartiklisse, kus vastav samm on ülevaatuseks esile tõstetud nuppudega Aktsepteeri ja Lükka tagasi

Klient kirjutab: “Teie juhend ütleb, et mine Seadete alla, siis Kalendrisse. Kalendrit ei ole.” Tal on õigus. Sa liigutasid selle kuus nädalat tagasi jaotisse Kontod. PR vaadati üle, testiti ja anti välja. Abiartikkel ei muutunud, sest kellegi töö ei olnud seda muuta.

Nii tekib peaaegu kogu aegunud dokumentatsioon. Mitte laiskusest, vaid puuduvast lülist “me muutsime toodet” ja “need artiklid kirjeldavad osa, mida me muutsime” vahel.

Selleks et hoida dokumentatsioon ajakohasena, kui annad iga nädal midagi välja, tee dokumentatsioon pull requesti osaks: iga PR vastab küsimusele “kas see muudab seda, mida klient näeb?”, nimetab abiartiklid, mida see mõjutab, ja toob dokumentatsiooni muudatuse samas PR-is või lingitud PR-is. Seejärel automatiseeri mehaanilised osad (ekraanipildid, muudatuslogi kirjed) ja jälgi tugipileteid ning abikeskuse otsinguid triivi suhtes, mis läbi lipsab.

Ülejäänud postitus on selle kohta, kuidas seda seadistada ilma tehnilist kirjutajat palkamata.

Miks dokumentatsioon aegub

Dokumentatsiooni triivil on mõned etteaimatavad põhjused ja ükski neist ei lahene sellega, et “olgem ettevaatlikumad.”

Dokumentatsioon elab mujal. Kood on GitHubis. Dokumentatsioon on Intercomis, Zendeskis, Notionis või GitBooki ruumis. Miski ei seo ühe faili teise lehega, nii et muudatus ühes ei anna märku teist vaatama.

Inimene, kes teab, ei ole inimene, kes kirjutab. Insener, kes liigutas kalendriseaded, teab täpselt, mis muutus. Inimene, kes abikeskust hooldab, saab teada kliendi käest.

Dokumentatsiooni parandatakse partiidena. “Teeme kvartali lõpus dokumentatsiooni läbivaatuse.” Samal ajal närib iga iganädalane väljalase täpsust ja suur ümberkirjutus võtab nii kaua aega, et on valmimise ajaks osaliselt aegunud.

Keegi ei tea, millised artiklid on mõjutatud. Isegi motiveeritud meeskond ei saa pärast iga väljalaset 80 artiklit kontrollida. Seega ei kontrolli nad ühtegi.

Illustreeriv diagramm dokumentatsiooni triivist ajas: kvartaalse ümberkirjutuse joon langeb pärast iga iganädalast väljalaset ja hüppab tagasi ainult ümberkirjutamisel, samas kui PR-ipõhiste uuenduste joon püsib kogu aeg täpsele lähedal

Muster on sama mis igas muus hooldustöös. Väikesed, pidevad uuendused võidavad perioodilised kangelastööd.

Tee dokumentatsioon osaks valmisoleku definitsioonist

Üks kõige tõhusam muudatus: lisa oma pull requesti malli dokumentatsiooni jaotis. GitHub täidab selle igal PR-il ette, kui paned faili asukohta .github/pull_request_template.md (GitHubi juhend PR-i mallide kohta).

## Docs impact

- [ ] This changes something a customer can see or do
- Help articles affected: <!-- slugs or links, or "none" -->
- [ ] Screenshots need re-capturing
- [ ] Changelog entry drafted (or marked "internal only")

Pull requesti mall jaotisega Dokumentatsiooni mõju: märkeruudud selle kohta, kas muudatus on kasutajale nähtav, milliseid abiartikleid see puudutab, kas ekraanipildid vajavad uuesti jäädvustamist ja kas muudatuslogi kirje on koostatud

Umbes kaks nädalat tundub see bürokraatiana. Siis muutub see hetkeks, kus insener ütleb “oh, sisseelamisartikkel mainib seda ekraani”, kuni kontekst on veel värske. Kahe-realine dokumentatsiooniparandus, mille kirjutab muudatuse teinud inimene, on parem kui täiuslik, mis on kuu aega hiljem oletuste põhjal kirjutatud.

Kaks reeglit panevad selle kinni jääma:

  1. Ülevaatajad kontrollivad märkeruudu. Kui PR ilmselgelt muudab kasutajaliidest ja ütleb “dokumentatsioonile mõju pole”, küsib ülevaataja, miks. Sama mis puuduva testi puhul.
  2. Dokumentatsiooni muudatus võib olla toores. Insenerid ei pea kirjutama viimistletud proosat. “Samm 6 nüüd: ava Kontod, siis Saadavuse seaded” on piisav. Keegi saab sõnastuse hiljem korda teha. Täpsus esimesena.

Kaardista abiartiklid koodiga, mida need kirjeldavad

PR-i kontrollnimekiri toetub sellele, et inimesed mäletavad, millised artiklid on olemas. Aita neid lihtsa kaardiga koodiradadelt artiklitele:

# docs-map.yml
- paths: ["src/features/calendar/**", "src/pages/accounts/availability*"]
  articles: ["connect-your-calendar", "set-your-availability"]
- paths: ["src/features/billing/**"]
  articles: ["change-your-plan", "update-payment-method", "download-invoices"]
- paths: ["src/features/onboarding/**"]
  articles: ["get-started"]

Seejärel loeb väike CI-samm muudetud failide nimekirja (git diff --name-only origin/main...HEAD), sobitab need glob-mustritega ja postitab PR-ile kommentaari: “See PR puudutab kalendrikoodi. Kontrolli: connect-your-calendar, set-your-availability.” See on ehk 40 rida skripti ja see muudab “mõtle dokumentatsioonile” konkreetseks, klõpsatavaks nimekirjaks.

Ka kaart aegub muidugi. Hoia see koodi kõrval ja lisa rida alati, kui keegi uue artikli kirjutab. See on ikka palju lihtsam hooldada kui dokumentatsioon ise.

Kui sinu dokumentatsioon elab samas repositooriumis (docs-as-code midagi sellist nagu Docusaurus, Mintlify või GitBooki Git Sync), saad minna kaugemale: CODEOWNERS kirje dokumentatsioonikaustal tagab, et keegi, kellele dokumentatsioon korda läheb, vaatab üle iga muudatuse selles.

Kirjuta dokumentatsiooni, mis mädaneb aeglasemalt

Mõned kirjutamisvalikud teevad dokumentatsiooni hoolduse palju lihtsamaks:

Rohkem struktuuri kohta meie juhendis abikeskuse artiklite kirjutamine, mida inimesed päriselt kasutavad.

Automatiseeri mehaanilised osad

Mõni dokumentatsiooni hooldus on otsustusvõime. Suur osa sellest on lihtsalt majapidamistööd, mida skript teeb paremini.

Ekraanipildid. Piltide käsitsi uuesti tegemine on esimene asi, mida automatiseerida. Playwrighti skript seedatud demokonto vastu, mida käivitatakse CI-s, annab sulle iga ühendamise puhul värsked, ühtlased pildid. Käime kogu skripti läbi artiklis kuidas ekraanipilte automaatselt luua.

Muudatuslogi kirjed. Sinu ühendatud PR-id kirjeldavad juba, mis välja läks. Nende muutmine kliendile suunatud muudatuslogiks tähendab enamasti inseneri keele ümberkirjutamist lihtsaks keeleks ja rühmitamist Added, Changed ja Fixed alla, konventsioon, mille tegi populaarseks Keep a Changelog. Mallide jaoks vaata kuidas kirjutada muudatuslogi, mida kliendid loevad.

Videod. Kui sul on juhendvideoid, ütleb sama koodiradade kaart, milliseid tuleb uuesti salvestada. Pildi ja hääle eraldi salvestamine teeb uuesti tegemise kiireks; siin on protsess toote juhendvideote jaoks.

Leia triiv, mis sul juba on

Isegi hea protsessi korral lipsavad mõned muudatused läbi. Need signaalid ütlevad, kus:

Ära dokumenteeri seda, mis pole välja läinud

Üks lõks kiiresti liikuvatele meeskondadele: PR ühendatakse funktsioonilipu taha, keegi uuendab kohusetundlikult dokumentatsiooni ja nüüd kirjeldab abikeskus funktsiooni, mida enamik kliente ei näe. Kliendid lähevad segadusse ja klienditugi saab piletid.

Hoia dokumentatsiooni muudatused lipu taga oleva töö jaoks tagasi, kuni lipp on kõigil sees (või kirjuta need mustanditena ja avalda koos väljalaskega). Sama kehtib muudatuslogi kirjete kohta.

Tööriistad, mis aitavad dokumentatsiooni hooldusel

Abilauad nagu Intercom, Zendesk ja Help Scout omavad täiesti häid abikeskuse redaktoreid, kuid nad ei tea, mis sinu koodis on, nii et kogu ülaltoodud linkimine on sinu kanda. Docs-as-code platvormid nagu GitBook ja Mintlify hoiavad dokumentatsiooni Gitis, mis annab PR-i ülevaatuse ja ajaloo, ning töötavad kõige paremini, kui sinu kirjutajad on repositooriumis mugavalt. Uuemad tehisintellekt-esimesed abikeskuse tööriistad, nende seas Ferndesk, püüavad lünka sulgeda teistest nurkadest.

Me ehitasime Ellie Docsi spetsiaalselt PR-i lingi ümber. Sa ühendad GitHubi repositooriumi ja Ellie kaardistab sinu funktsioonid ning seob iga abiartikli funktsioonidega, mida see kirjeldab. Iga ühendatud PR-i puhul kontrollib see, milliseid artikleid muudatus mõjutab, ja pakub muudatusi välja ülevaadatava diffina koos lühikese selgitusega, miks. Sa aktsepteerid või lükkad tagasi igaühe. Miski ei avaldu ise.

Ellie Docsi soovitatud uuendus artiklile "Ühenda oma kalender ja eelvaata saadavust" pärast ühendatud PR-i, mis näitab aegunud sammu punasega läbi kriipsutatuna, uusi samme roheliselt ning nuppe Aktsepteeri ja Lükka tagasi

See koostab muudatuslogi kirjeid ka samadest ühendatud PR-idest ja hoiab tagasi kõike, mis on veel lipu taga, kuni see on välja lastud.

Ellie Docsi muudatuslogi leht kirjetega, mis on koostatud lükatud koodist, sealhulgas uus saadavuse seadete paneel, igaüks lingitud seotud abiartikliga ja avaldamiseks valmis

Sa saad kõike selles postituses käsitsi teha ja paljud meeskonnad teevad. Ellie lihtsalt teeb sinu eest osa “milliseid artikleid see PR mõjutab ja mida peaks muutma?” iga kord.

Levinud küsimused

Kes peaks väikeses meeskonnas dokumentatsiooni omama? Üks nimeline inimene omab abikeskust tervikuna (sageli asutaja või see, kes klienditoega tegeleb), kuid iga insener omab oma PR-ide dokumentatsioonimõju. Jagatud omandiõigus ilma nimelise omanikuta tähendab, et omanikku pole.

Kui tihti peaksime oma dokumentatsiooni üle vaatama? Muudatuste puhul pidevalt (PR-i kontrollnimekirja kaudu) pluss igakuine läbiklõpsamine enimvaadatud artiklitest. Suured kvartaalsed ümberkirjutused on märk, et pidev osa ei toimu.

Kas docs-as-code tasub klientide abidokumentatsiooni jaoks ära? Kui kirjutajad on insenerid, siis jah. Kui enamiku kirjutab klienditugi või turundus, töötab tavaline abikeskuse redaktor pluss PR-i kontrollnimekiri ja dokumentatsioonikaart tavaliselt paremini kui kõigi sundimine Giti.

Mis on kiireim võit, kui meie dokumentatsioon on juba tugevalt aegunud? Paranda liikluse järgi 10 parimat artiklit, lisa PR-i mall ja hakka märgistama tugipileteid, mis dokumentatsiooni mainivad. See peatab veritsemise enne, kui võtad ette pika saba.

Kui eelistad, et dokumentatsiooni uuendusi pakutaks sulle välja iga PR-i puhul, proovi Ellie Docsi tasuta. Ühenda repositoorium, saa koostatud abikeskus ja vaata ülevaatuseks soovitatud muudatused, kui annad välja.