Dokumentatsioon on tarkvara arendustsükli oluline osa. See selgitab tarkvara kasutamist ja võib sisaldada kasutusjuhendeid, API viiteid, installijuhiseid ja väljalaskemärkmeid.
Dokumentatsiooni automatiseerimine on uusim trend, kuna see aitab säästa aega, vähendada vigu ja tagada järjepidevuse. Oma dokumentatsiooni ajakohasena ja kõigile sidusrühmadele juurdepääsetav hoidmine hõlbustab koostööd ja pidevat täiustamist.
Dokumendid koodina on lähenemine dokumentatsiooni automatiseerimisele, mis käsitleb tehnilist dokumentatsiooni koodina.
Mis on Docs kui kood?
Dokumendid kui kood on tarkvaraarenduse filosoofia, mis käsitleb tehnilist dokumentatsiooni kui koodi vormi. See soovitab käsitleda dokumentatsiooni sama ranguse ja protsessiga nagu tarkvarakoodi.
Dokumendi kui koodi idee on käsitleda dokumentatsiooni arendusprotsessi esmaklassilise artefaktina, integreerides selle tarkvara elutsükliga. See tähendab, et dokumentatsiooni käsitletakse koodibaasi lahutamatu osana. See tähendab sama versioonikontrolli, pidevat integreerimist ja testimisprotsesside rakendamist, mida teete koodile endale.
Tavalistes dokumentides, nagu koodi seadistus, kirjutate dokumentatsiooni lihttekstifailides, tavaliselt sees kerge märgistuskeel nagu Markdown, HTML või reStructuredText. Seejärel salvestate selle lähtekoodiga samasse hoidlasse. See muudab nii tarkvara kui ka dokumentatsiooni muudatuste haldamise ja jälgimise lihtsaks. Samuti aitab see tagada, et dokumentatsioon on koodi uusima versiooniga ajakohane.
Miks peaksite koodina kasutama dokumente?
Enne dokumente kui koodi käsitleti dokumentatsiooni sageli koodist eraldiseisvana, mis loodi erinevate tööriistade ja protsessidega. Selline lõdvem lähenemine põhjustas sageli aegunud dokumentatsiooni ja vastuolusid koodiga. Saate kasutada mitmeid eeliseid, kui kasutate dokumente koodipõhise lähenemisviisina.
Täiustatud koostöö
Dokumendid koodina võimaldavad koostööd arendajate, tehniliste kirjutajate ja teiste arendusprotsessi sidusrühmade vahel. Kuna koodihoidlas on dokumentatsioon, on erinevatel osapooltel lihtne panustada ja muudatusi teha. See aitab tagada, et dokumentatsioon on täpne, ajakohane ja kõikehõlmav.
Koostööpõhine lähenemine dokumentatsioonile aitab tagada, et see sisaldab kogu asjakohast teavet ja kajastab täpselt tarkvarasüsteemi nii, nagu kõik osapooled seda tõlgendavad.
Protsesside automatiseerimine ja juurdepääsetavus
Dokumentide kui koodi teine eelis on see, et see võimaldab automatiseeritud tööriistu dokumentatsiooni genereerida ja avaldada. Koostamissüsteem võib automaatselt genereerida lihttekstifailidest dokumentatsiooni HTML- või PDF-versioonid, mis avaldatakse veebisaidil või sisemises dokumentatsiooniportaalis. See muudab dokumentatsiooni kättesaadavaks suuremale hulgale sidusrühmadele.
Dokumentatsiooni loomise ja avaldamise protsessi automatiseerimisega aitab dokumendid koodina vähendada dokumentatsiooni hooldamiseks ja avaldamiseks kuluvat aega ja vaeva. See võimaldab arendusmeeskondadel keskenduda tarkvara täiustamisele.
Versioonikontroll
Dokumentatsiooni säilitamine tarkvaraga samas koodihoidlas muudab mõlema muudatuste haldamise ja jälgimise lihtsaks.
Sa võid kasutada versioonikontrollisüsteemid nagu Git, et jälgida dokumentatsiooni muudatusi ja vajadusel naasta eelmistele versioonidele. See aitab tagada, et dokumentatsioon on täpne ja ajakohane ning saate muudatusi jälgida ja auditeerida.
Tüüpilised dokumendid koodina töövoog
Tüüpilised dokumendid koodi töövoona hõlmavad kirjutamist, versioonikontrolli, koostamist ja hostimist:
Kirjutamisprotsess
Kirjutamisprotsess on tüüpilise dokumentide kui koodi töövoo esimene etapp. Enamik tehnilised kirjanikud ja dokumentatsiooniinsenerid kasutavad lihtsat MarkDowni, AsciiDoci või HTML-i. Nad kirjutavad dokumentatsiooni selliste tööriistadega nagu GitBook ja Redocly, mis tagavad sujuva protsessi.
Dokumentatsiooni versioonikontroll
Dokumentatsioon areneb koodi arenedes. Vajate keerukat versioonihaldussüsteemi, nagu Git, Plastic SCM või Subversion, et jälgida dokumentatsiooni muudatusi, et hõlbustada koostööd ja versioonide jälgimist.
Dokumentatsiooni koostamise protsess
Koostamisprotsess hõlmab dokumentatsiooni töötlemist ja koostamist tarnevormingutesse. Need võivad olla HTML, PDF, EPUB või muud. Dokumenteerimisprotsessi lihtsustatakse tavaliselt staatiliste saidigeneraatorite, nagu Hugo ja Jekyll, abil.
Dokumentatsiooni hostimine ja levitamine
Hostimis- või levitamisprotsess on tavaliselt dokumentide kodeerimisprotsessi viimane etapp. See protsess tagab, et dokumentatsioon jõuab lõppkasutajale ja on kättesaadav kõigile sidusrühmadele. Dokumentatsiooni veebis levitamiseks saate kasutada GitHubi või GitLabi lehti või kohandatud portaali.
GoDoc ja JavaDoc abil saate automatiseerida Go ja Java dokumentatsiooni
Dokumendid kui koodifilosoofia muudavad tehnilise dokumentatsiooni kirjutamise ja haldamise revolutsiooniliseks.
Paljud programmeerimiskeeled, sealhulgas Go ja Java, pakuvad tööriistu dokumentatsiooni automatiseerimiseks koodikommentaaride abil. Go pakub Godoci tööriista ja Java pakub JavaDocit.
