Dokumentointi on olennainen osa ohjelmistokehityssykliä. Se selittää, kuinka ohjelmistoa käytetään, ja se voi sisältää käyttöoppaita, API-viittauksia, asennusohjeita ja julkaisutietoja.
Dokumentaation automatisointi on uusin trendi, koska se voi säästää aikaa, vähentää virheitä ja varmistaa johdonmukaisuuden. Dokumentaation pitäminen ajan tasalla ja kaikkien sidosryhmien saatavilla helpottaa yhteistyötä ja jatkuvaa parantamista.
Docs as code on lähestymistapa dokumentoinnin automatisointiin, joka käsittelee teknistä dokumentaatiota koodina.
Mikä on Docs koodina?
Docs as code on ohjelmistokehitysfilosofia, joka pitää teknistä dokumentaatiota koodin muotona. Se ehdottaa, että sinun tulee käsitellä dokumentaatiota samalla tarkkuudella ja prosessilla kuin ohjelmistokoodia.
Docsin ideana koodina on käsitellä dokumentaatiota kehitysprosessin ensiluokkaisena artefaktina ja integroida se ohjelmiston elinkaareen. Tämä tarkoittaa, että dokumentaatiota käsitellään koodikannan olennaisena osana. Se tarkoittaa, että siihen sovelletaan samaa versionhallintaa, jatkuvaa integrointia ja testausprosesseja kuin itse koodiin.
Tyypillisessä dokumentissa koodiasetuksissa kirjoitat dokumentaatiot pelkkää tekstiä sisältäviin tiedostoihin, yleensä sisään kevyt merkintäkieli, kuten Markdown, HTML tai reStructuredText. Tallennat sen sitten samaan arkistoon kuin lähdekoodi. Näin ohjelmistoon ja dokumentaatioon tehtyjen muutosten hallinta ja seuranta on helppoa. Se auttaa myös varmistamaan, että dokumentaatio on ajan tasalla koodin uusimman version kanssa.
Miksi sinun pitäisi käyttää dokumentteja koodina
Ennen dokumentteja koodina dokumentaatiota käsiteltiin usein koodista erillisenä, eri työkaluilla ja prosesseilla luotuina. Tämä löysempi lähestymistapa johti usein vanhentuneisiin dokumentaatioihin ja epäjohdonmukaisuuksiin koodin kanssa. Voit hyödyntää useita etuja ottamalla asiakirjat käyttöön koodimenetelmänä.
Parempi yhteistyö
Docs koodina mahdollistaa yhteistyön kehittäjien, teknisten kirjoittajien ja muiden kehitysprosessin sidosryhmien välillä. Koska dokumentaatio on koodivarastossa, eri osapuolten on helppo osallistua ja tehdä muutoksia. Tämä auttaa varmistamaan, että dokumentaatio on tarkka, ajan tasalla ja kattava.
Yhteistyöllinen lähestymistapa dokumentointiin auttaa varmistamaan, että se sisältää kaikki olennaiset tiedot ja että se kuvastaa tarkasti ohjelmistojärjestelmää kaikkien osapuolten tulkitsemana.
Prosessien automatisointi ja saavutettavuus
Toinen asiakirjojen etu koodina on, että se mahdollistaa automaattiset työkalut dokumenttien luomiseen ja julkaisemiseen. Rakennusjärjestelmä voi automaattisesti luoda HTML- tai PDF-versioita dokumentaatiosta pelkistä tekstitiedostoista julkaistavaksi verkkosivustolle tai sisäiseen dokumentaatioportaaliin. Näin asiakirjat ovat useammille sidosryhmille saatavilla.
Dokumentaation luonti- ja julkaisuprosessin automatisoimalla asiakirjat koodina auttavat vähentämään dokumentaation ylläpitoon ja julkaisemiseen kuluvaa aikaa ja vaivaa. Sen avulla kehitystiimit voivat keskittyä ohjelmiston parantamiseen.
Versionhallinta
Dokumentaation tallentaminen samaan koodivarastoon ohjelmiston kanssa helpottaa molempien muutosten hallintaa ja seurantaa.
Voit käyttää versionhallintajärjestelmät kuten Git, jotta voit seurata dokumentaatiomuutoksia ja palata tarvittaessa aikaisempiin versioihin. Tämä auttaa varmistamaan, että dokumentaatio on tarkka ja ajan tasalla, ja voit jäljittää ja tarkastaa muutokset.
Tyypilliset asiakirjat koodina -työnkulku
Tyypilliset dokumentit koodityönkuluna sisältävät kirjoittamisen, versionhallinnan, rakentamisen ja isännöinnin:
Kirjoitusprosessi
Kirjoitusprosessi on tyypillisen dokumenttien koodityönkulun ensimmäinen vaihe. Suurin osa tekniset kirjoittajat ja dokumentointiinsinöörit käyttävät yksinkertaista MarkDown-, AsciiDoc- tai HTML-koodia. He kirjoittavat dokumentaation käyttämällä työkaluja, kuten GitBook ja Redocly, jotka varmistavat sujuvan prosessin.
Versionhallinta dokumentaatiota varten
Dokumentaatio kehittyy koodin kehittyessä. Tarvitset kehittyneen versionhallintajärjestelmän, kuten Git, Plastic SCM tai Subversion dokumentaatiomuutosten seuraamiseen helpottamaan yhteistyötä ja versioseurantaa.
Dokumentaation rakennusprosessi
Rakennusprosessi sisältää dokumentaation käsittelyn ja kokoamisen toimitusmuotoihinsa. Nämä voivat olla HTML-, PDF-, EPUB- tai muita. Dokumentointiprosessia helpotetaan yleensä käyttämällä staattisia sivustogeneraattoreita, kuten Hugo ja Jekyll.
Dokumentaation ylläpito ja jakelu
Isännöinti- tai jakeluprosessi on yleensä dokumenttien viimeinen vaihe koodausprosessina. Tämä prosessi varmistaa, että dokumentaatio toimitetaan loppukäyttäjälle ja on kaikkien sidosryhmien saatavilla. Voit käyttää GitHub- tai GitLab-sivuja tai mukautettua portaalia dokumentaation jakamiseen verkossa.
Voit automatisoida Go- ja Java-dokumentaation käyttämällä GoDoc- ja JavaDoc-ohjelmaa
Docs koodifilosofiana mullistaa teknisen dokumentaation kirjoittamisen ja hallinnan.
Monet ohjelmointikielet, mukaan lukien Go ja Java, tarjoavat työkaluja dokumentoinnin automatisointiin koodikommenttien avulla. Go tarjoaa Godoc-työkalun ja Java JavaDoc-työkalun.
