Dokumentacija je bistven del cikla razvoja programske opreme. Pojasnjuje, kako uporabljati programsko opremo in lahko vključuje uporabniške priročnike, reference API-jev, navodila za namestitev in opombe ob izdaji.
Avtomatizacija vaše dokumentacije je najnovejši trend, saj lahko prihrani čas, zmanjša število napak in zagotovi doslednost. Posodabljanje vaše dokumentacije in dostopnost vsem zainteresiranim stranem olajšata sodelovanje in stalne izboljšave.
Dokumenti kot koda je pristop k avtomatizaciji dokumentacije, ki tehnično dokumentacijo obravnava kot kodo.
Kaj so dokumenti kot koda?
Dokumenti kot koda je filozofija razvoja programske opreme, ki na tehnično dokumentacijo gleda kot na obliko kode. Predlaga, da dokumentacijo obravnavate enako strogo in enako kot programsko kodo.
Ideja dokumentov kot kode je obravnavati dokumentacijo kot prvorazredni artefakt razvojnega procesa in jo integrirati v življenjski cikel programske opreme. To pomeni, da dokumentacijo obravnavamo kot sestavni del kodne baze. To pomeni, da zanjo uporabite enak nadzor različic, stalno integracijo in postopke testiranja, kot jih izvajate za samo kodo.
V tipični dokumentaciji kot nastavitev kode napišete dokumentacijo v datoteke z navadnim besedilom, običajno v lahek označevalni jezik, kot je Markdown, HTML ali reStructuredText. Nato ga shranite v isti repozitorij kot izvorno kodo. To olajša upravljanje in sledenje spremembam programske opreme in dokumentacije. Prav tako pomaga zagotoviti, da je dokumentacija posodobljena z najnovejšo različico kode.
Zakaj bi morali uporabljati dokumente kot kodo
Pred dokumenti kot kodo je bila dokumentacija pogosto obravnavana kot ločena od kode, ustvarjena z različnimi orodji in postopki. Ta ohlapnejši pristop je pogosto vodil do zastarele dokumentacije in nedoslednosti s kodo. S sprejetjem pristopa dokumentov kot kode lahko izkoristite več prednosti.
Izboljšano sodelovanje
Dokumenti kot koda omogočajo sodelovanje med razvijalci, tehničnimi pisci in drugimi deležniki v razvojnem procesu. Ker je v skladišču kode shranjena dokumentacija, je za različne strani enostavno prispevati in spreminjati. To pomaga zagotoviti, da je dokumentacija točna, posodobljena in celovita.
Sodelovalni pristop k dokumentaciji pomaga zagotoviti, da vključuje vse pomembne informacije in da natančno odraža programski sistem, kot ga razlagajo vse strani.
Avtomatizacija procesov in dostopnost
Druga prednost dokumentov kot kode je, da omogoča avtomatiziranim orodjem za ustvarjanje in objavljanje dokumentacije. Gradbeni sistem lahko samodejno ustvari HTML ali PDF različice dokumentacije iz datotek z navadnim besedilom za objavo na spletnem mestu ali internem dokumentacijskem portalu. Tako je dokumentacija dostopna večjemu številu deležnikov.
Z avtomatizacijo procesa ustvarjanja in objavljanja dokumentacije dokumenti kot koda pomagajo skrajšati čas in trud, potreben za vzdrževanje in objavljanje dokumentacije. Razvojnim ekipam omogoča, da se osredotočijo na izboljšanje programske opreme.
Nadzor različic
Shranjevanje dokumentacije v istem repozitoriju kode kot programska oprema olajša upravljanje in sledenje spremembam obeh.
Lahko uporabiš sistemi za nadzor različic kot je Git za sledenje spremembam dokumentacije in po potrebi vrnitev na prejšnje različice. To pomaga zagotoviti, da je dokumentacija točna in posodobljena, poleg tega lahko sledite in revidirate spremembe.
Tipični dokumenti kot potek dela kode
Tipični potek dela dokumentov kot kode vključuje pisanje, nadzor različic, gradnjo in gostovanje:
Proces pisanja
Postopek pisanja je prva stopnja tipičnega delovnega toka dokumentov kot kode. večina tehnični pisci in dokumentacijski inženirji uporabljajo preprost MarkDown, AsciiDoc ali HTML. Dokumentacijo pišejo z orodji, kot sta GitBook in Redocly, ki zagotavljajo nemoten postopek.
Nadzor različic za dokumentacijo
Dokumentacija se razvija z razvojem kode. Potrebovali boste prefinjen sistem za nadzor različic, kot je Git, Plastic SCM ali Subversion, da boste spremljali spremembe dokumentacije za lažje sodelovanje in sledenje različicam.
Postopek izdelave dokumentacije
Postopek izdelave vključuje obdelavo in zbiranje dokumentacije v formate za dostavo. To so lahko HTML, PDF, EPUB ali drugi. Postopek dokumentacije je običajno olajšan z uporabo statičnih generatorjev spletnih mest, kot sta Hugo in Jekyll.
Gostovanje in distribucija dokumentacije
Postopek gostovanja ali distribucije je običajno zadnji korak v procesu kodiranja dokumentov. Ta proces zagotavlja, da je dokumentacija dostavljena končnemu uporabniku in na voljo vsem zainteresiranim stranem. Za distribucijo svoje dokumentacije v spletu lahko uporabite strani GitHub ali GitLab ali portal po meri.
Dokumentacijo Go in Java lahko avtomatizirate z uporabo GoDoc in JavaDoc
Dokumentacija kot filozofija kode revolucionira pisanje in upravljanje tehnične dokumentacije.
Številni programski jeziki, vključno z Go in Javo, ponujajo orodja za avtomatizacijo dokumentacije z uporabo komentarjev kode. Go ponuja orodje Godoc, Java pa JavaDoc.