Kuidas hoida dokumentatsioon ajakohasena, kui annad iga nädal midagi välja
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.
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")
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:
- Ülevaatajad kontrollivad märkeruudu. Kui PR ilmselgelt muudab kasutajaliidest ja ütleb “dokumentatsioonile mõju pole”, küsib ülevaataja, miks. Sama mis puuduva testi puhul.
- 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:
- Kirjelda ülesandeid, mitte paigutusi. “Ava Kontod ja vali Saadavuse seaded” elab ümberdisaini üle. “Klõpsa paremas ülanurgas lillat nuppu” ei ela.
- Kasuta täpseid kasutajaliidese silte paksus kirjas. Kui silt muutub, leiab vana sildi otsing üles iga artikli, mis vajab parandamist.
- Ära korda muutuvaid fakte. Plaanipiirangud, hinnad ja prooviaja pikkused muutuvad. Pane need ühele lehele ja lingi sellele, selle asemel et neid kümnes artiklis uuesti välja öelda.
- Tee ekraanipilt stabiilsest osast. Kärbi elemendi järgi, mille kohta samm käib, mitte kogu ekraani, et külgriba muutus ei tühistaks iga pilti.
- Näita kuupäeva “viimati uuendatud”. See hoiab sind ausana ja ütleb lugejatele, kui palju lehte usaldada.
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:
- Tugipiletid, mis tsiteerivad sinu dokumentatsiooni. “Juhend ütleb X, aga ma näen Y” on tasuta veaaruanne. Märgi need ja paranda artikkel samal päeval.
- Abikeskuse otsingud ilma tulemusteta. Inimesed otsivad funktsiooni nime, mille ümber nimetasid, või funktsiooni, mida sa kunagi ei dokumenteerinud.
- Artikli tagasiside. Kui sinu abikeskuses on “Kas see oli abiks?”, loe pöidla-alla kommentaare iga nädal. Need on tavaliselt konkreetsed.
- Lühike ülevaatus oma enimvaadatud lehtedest. Kord kuus klõpsa läbi oma 20 enimvaadatud artiklit päris tootes. See võtab umbes tunni ja katab suurema osa sellest, mida kliendid tegelikult loevad.
Ä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.

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.

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.