Dokumentacija je bitan dio ciklusa razvoja softvera. Objašnjava kako koristiti softver i može uključivati korisničke vodiče, API reference, upute za instalaciju i napomene o izdanju.
Automatizacija vaše dokumentacije najnoviji je trend jer može pomoći uštedjeti vrijeme, smanjiti pogreške i osigurati dosljednost. Održavanje vaše dokumentacije ažurnom i dostupnom svim dionicima olakšava suradnju i kontinuirano poboljšanje.
Dokumenti kao kod pristup su automatizaciji dokumentacije koji tehničku dokumentaciju tretira kao kod.
Što su dokumenti kao kod?
Dokumenti kao kod filozofija su razvoja softvera koja na tehničku dokumentaciju gleda kao na oblik koda. Sugerira da biste dokumentaciju trebali tretirati s istom strogošću i procesom kao i softverski kod.
Ideja iza dokumenata kao koda jest tretirati dokumentaciju kao prvorazredni artefakt razvojnog procesa, integrirajući je sa životnim ciklusom softvera. To znači tretirati dokumentaciju kao sastavni dio baze koda. To znači primijeniti na njega istu kontrolu verzija, kontinuiranu integraciju i postupke testiranja koje provodite na samom kodu.
U tipičnom postavljanju koda za dokumente, dokumentaciju pišete u obične tekstualne datoteke, obično u lagani označni jezik kao što je Markdown, HTML ili reStructuredText. Zatim ga pohranjujete u isto spremište kao i izvorni kod. To olakšava upravljanje i praćenje promjena u softveru i dokumentaciji. Također pomaže osigurati da je dokumentacija ažurirana s najnovijom verzijom koda.
Zašto biste trebali koristiti dokumente kao kod
Prije dokumenata kao koda, dokumentacija se često tretirala kao odvojena od koda, stvorena različitim alatima i procesima. Ovaj labaviji pristup često je dovodio do zastarjele dokumentacije i nedosljednosti s kodom. Možete iskoristiti nekoliko prednosti usvajanjem pristupa dokumentima kao kodu.
Poboljšana suradnja
Dokumenti kao kôd omogućuju suradnju između programera, tehničkih pisaca i drugih dionika u procesu razvoja. Budući da se u repozitoriju kodova nalazi dokumentacija, različitim je stranama lako doprinijeti i unijeti izmjene. To pomaže osigurati da je dokumentacija točna, ažurna i sveobuhvatna.
Suradnički pristup dokumentaciji pomaže osigurati da ona uključuje sve relevantne informacije i da točno odražava softverski sustav kako ga tumače sve strane.
Automatizacija procesa i pristupačnost
Još jedna prednost dokumenata kao koda je ta što omogućuje automatiziranim alatima za generiranje i objavljivanje dokumentacije. Sustav za izradu može automatski generirati HTML ili PDF verzije dokumentacije iz običnih tekstualnih datoteka za objavljivanje na web stranici ili portalu interne dokumentacije. To dokumentaciju čini dostupnom većem broju dionika.
Automatizirajući proces generiranja i objavljivanja dokumentacije, dokumenti kao kod pomažu u smanjenju vremena i truda potrebnih za održavanje i objavljivanje dokumentacije. Omogućuje razvojnim timovima da se usredotoče na poboljšanje softvera.
Kontrola verzija
Pohranjivanje dokumentacije u istom repozitoriju koda kao i softver olakšava upravljanje i praćenje promjena u oba.
Možeš koristiti sustavi kontrole verzija poput Gita za praćenje promjena dokumentacije i vraćanje na prethodne verzije ako je potrebno. To pomaže osigurati da je dokumentacija točna i ažurna, a možete pratiti i revidirati promjene.
Tipični dokumenti kao tijek rada koda
Tipični radni tijek dokumenata kao koda uključuje pisanje, kontrolu verzija, izgradnju i hosting:
Proces pisanja
Proces pisanja prva je faza tipičnog tijeka rada dokumenata kao koda. Najviše tehnički pisci i dokumentacijski inženjeri koriste jednostavni MarkDown, AsciiDoc ili HTML. Oni pišu dokumentaciju pomoću alata kao što su GitBook i Redocly koji osiguravaju nesmetan proces.
Kontrola verzija za dokumentaciju
Dokumentacija se razvija kako se kod razvija. Trebat će vam sofisticirani sustav kontrole verzija kao što je Git, Plastic SCM ili Subversion za praćenje promjena dokumentacije radi lakše suradnje i praćenja verzija.
Proces izrade dokumentacije
Proces izgradnje uključuje obradu i sastavljanje dokumentacije u formate za isporuku. To mogu biti HTML, PDF, EPUB ili drugi. Proces dokumentacije obično se olakšava korištenjem generatora statičkih stranica kao što su Hugo i Jekyll.
Hosting i distribucija dokumentacije
Proces hostinga ili distribucije obično je posljednji korak u procesu kodiranja dokumenata. Ovaj proces osigurava da je dokumentacija dostavljena krajnjem korisniku i dostupna svim dionicima. Za distribuciju svoje dokumentacije na webu možete koristiti GitHub ili GitLab stranice ili prilagođeni portal.
Možete automatizirati Go i Java dokumentaciju koristeći GoDoc i JavaDoc
Dokumenti kao filozofija koda revolucionariziraju pisanje i upravljanje tehničkom dokumentacijom.
Mnogi programski jezici, uključujući Go i Java, pružaju alate za automatizaciju dokumentacije pomoću komentara koda. Go pruža alat Godoc, a Java pruža JavaDoc.
