Enamik dokumentatsioonimeeskondi, keda tean, kirjutab nüüd Markdownis. Dokumendid on kaustas, sageli koodiga samas repositooriumis, ja ehitus teeb neist abikeskuse. Kirjutajatele see meeldib ja ka agentidele, kellega nad töötavad, sest tavaliste tekstifailide kaust on agendile kõige lihtsam asi, mida lugeda ja muuta.
Need, kes dokumentatsiooni heaks kiidavad, seal ei tööta. Insener, kes peab API käitumise kinnitama, tootejuht, kelle oma see funktsioon on, jurist, kes loeb läbi iga lause andmete kohta. Nemad elavad Google Docsis. Dokumendile jätavad nad meelsasti kommentaari, pull requesti nad ei ava.
Koopia, mis vananeb
Nii teebki kirjutaja koopia. Kleebib Markdowni uude Google Docsi dokumenti, parandab vormingu, mille kleepimine lõhkus, ja jagab linki. Retsensendid kommenteerivad, kirjutaja teeb muudatused Markdownis ja nüüd on lehest kaks versiooni.
Valus on teine ring. Kas kleebid uuesti uude dokumenti ja saadad uue lingi, nii et vanad kommentaarid jäävad versioonile, mida keegi enam lugema ei peaks. Või muudad vana dokumenti käsitsi samaks ja loodad, et midagi kahe silma vahele ei jäänud. Kolmandaks ringiks kommenteerib keegi faili „Release notes 3.2 (copy) v2 FINAL“ ja küsimus, milline neist kehtib, võtab kauem aega kui ülevaatus ise.
Üks dokument, mida uuendatakse kohapeal
Ritemark 1.12.0 tõi kaasa Google Docsis avaldamise. Igas Markdown-dokumendis teeb Export → Create Google Doc sinu enda Drive'i Google Docsi dokumendi lehe pealkirjade, loendite, tabelite, koodi ja piltidega. Mermaidi ja draw.io joonised jõuavad sinna piltidena. Seda dokumenti jagad nii, nagu jagad iga teist.
Kui järgmise ringi muudatused on Markdownis tehtud, paneb Export → Sync Google Doc sinu praeguse teksti samasse dokumenti. Link jääb, jagamine jääb ja kellegi Drive'i ei teki uut koopiat. Kui valisid malli, jäävad alles ka selle fondid, päis ja jalus, sest Sync asendab ainult teksti. Retsensendid avavad lingi, mis neil juba on, ja loevad seda versiooni, mis sul praegu on.
Markdown-fail jääb originaaliks. Google Docsist ei tule sinna midagi tagasi, nii et kellegi muudatused Google'is ei puuduta dokumentatsiooni kausta, ehitust ega seda, mida agent selles kaustas teeb.
Ringid, mitte ühine mustand
See ühesuunalisus kujundab ülevaatuse käigu ja retsensentidele tasub sellest kohe alguses öelda.
Palu neil dokumenti mitte muuta, vaid kommenteerida. Nende kommentaarid on ringi sisend. Loed need läbi, teed muudatused Markdownis ise või palud agendil teha need kõigil lehtedel, mida need puudutavad, ja siis sünkroonid. Kui keegi on pärast viimast sünkroonimist dokumenti siiski otse kirjutanud, hoiatab Ritemark enne ülekirjutamist ja pakub võimalust dokument enne avada, et saaksid tema muudatuse käsitsi üle tuua. Kahte versiooni kokku sulatada see ei oska ega teeskle, et oskab.
Kommentaarid, mis jätad Ritemarkis iseendale, jäävad Ritemarki. Dokumenti neid ei avaldata ja tavaliselt on see just see, mida tahad, sest „kontrolli see Priyaga üle“ ei ole märkus Priya juhile.
Mida see ei tee
Pea seda avaldamise sammuks. Midagi ei juhtu enne, kui valid Sync, kahesuunalist muutmist ei ole ja abikeskuse leht ei ole Google Docsi dokumendiga seotud, kui sa seda ei avalda. Mõni asi teekonda üle ei ela: märgitud linnuke saabub märkimata ja nummerdatud punkti all olevad täpploendid näitavad tähti, mõlemad Google'i API piirangud. Avaldamine saadab lehe Google'ile sinu enda Drive'i ja ainult siis, kui valid Create või Sync. Ritemark küsib ühe kitsa loa, mis katab tema loodud dokumendid ja sinu valitud malli ning mitte midagi muud sinu Drive'is.
Tehnilise kirjutaja jaoks on muudatus väike, mõju mitte. Tõe allikas jääb sinna, kus on sinu tööriistad, ja need, kes dokumentatsiooni heaks kiidavad, loevad seda edasi seal, kus nad niikuinii on, ühe lingi all, mis on alati ajakohane.
Google Docsis avaldamise juhend räägib seadistamisest, mallidest ja sellest, mis üle tuleb, ning tehniliste kirjutajate leht näitab, kuhu see sobitub väljalaskemärkmete, API dokumentatsiooni ja teadmusbaasi töö kõrval.