Dokumentacija yra esminė programinės įrangos kūrimo ciklo dalis. Jame paaiškinama, kaip naudoti programinę įrangą, ir gali būti vartotojo vadovai, API nuorodos, diegimo instrukcijos ir leidimo pastabos.
Dokumentacijos automatizavimas yra naujausia tendencija, nes tai gali padėti sutaupyti laiko, sumažinti klaidų skaičių ir užtikrinti nuoseklumą. Jei dokumentai nuolat atnaujinami ir prieinami visoms suinteresuotosioms šalims, tai palengvina bendradarbiavimą ir nuolatinį tobulėjimą.
Dokumentai kaip kodas – tai dokumentacijos automatizavimo metodas, kuris techninę dokumentaciją traktuoja kaip kodą.
Kas yra Dokumentai kaip kodas?
Dokumentai kaip kodas yra programinės įrangos kūrimo filosofija, kuri techninę dokumentaciją vertina kaip kodo formą. Tai rodo, kad su dokumentais turėtumėte elgtis taip pat griežtai ir kaip su programinės įrangos kodu.
Dokumentų kaip kodo idėja yra traktuoti dokumentus kaip pirmos klasės kūrimo proceso artefaktą, integruojant jį su programinės įrangos gyvavimo ciklu. Tai reiškia, kad dokumentai laikomi neatskiriama kodų bazės dalimi. Tai reiškia, kad taikysite tą patį versijos valdymą, nuolatinį integravimą ir testavimo procesus, kuriuos taikote pačiam kodui.
Įprastuose dokumentuose, kaip kodo sąrankoje, dokumentaciją rašote paprasto teksto failais, dažniausiai į lengva žymėjimo kalba, pvz., Markdown, HTML arba reStructuredText. Tada saugote jį toje pačioje saugykloje kaip ir šaltinio kodą. Tai leidžia lengvai valdyti ir stebėti programinės įrangos ir dokumentacijos pakeitimus. Tai taip pat padeda užtikrinti, kad dokumentuose būtų naujausia kodo versija.
Kodėl turėtumėte naudoti dokumentus kaip kodą
Prieš dokumentus kaip kodą, dokumentacija dažnai buvo traktuojama kaip atskira nuo kodo, sukurta naudojant skirtingus įrankius ir procesus. Šis laisvesnis požiūris dažnai lėmė pasenusią dokumentaciją ir neatitikimus kodui. Naudodami dokumentus kaip kodą, galite pasinaudoti keliais pranašumais.
Patobulintas bendradarbiavimas
Dokumentai kaip kodas įgalina kūrėjų, techninių rašytojų ir kitų suinteresuotųjų šalių bendradarbiavimą kūrimo procese. Kadangi kodų saugykloje saugoma dokumentacija, įvairios šalys gali lengvai prisidėti ir atlikti pakeitimus. Tai padeda užtikrinti, kad dokumentai būtų tikslūs, atnaujinami ir išsamūs.
Bendradarbiaujantis požiūris į dokumentaciją padeda užtikrinti, kad į ją būtų įtraukta visa svarbi informacija ir kad ji tiksliai atspindėtų programinės įrangos sistemą, kurią interpretuoja visos šalys.
Procesų automatizavimas ir prieinamumas
Kitas dokumentų, kaip kodo, privalumas yra tai, kad jis leidžia automatizuotiems įrankiams kurti ir publikuoti dokumentus. Sukūrimo sistema gali automatiškai generuoti dokumentacijos HTML arba PDF versijas iš paprasto teksto failų, kad būtų galima paskelbti svetainėje arba vidiniame dokumentų portale. Taip dokumentacija tampa prieinama daugiau suinteresuotųjų šalių.
Automatizuodami dokumentacijos kūrimo ir publikavimo procesą, dokumentai kaip kodas padeda sumažinti laiką ir pastangas, kurių reikia dokumentacijai prižiūrėti ir paskelbti. Tai leidžia kūrėjų komandoms sutelkti dėmesį į programinės įrangos tobulinimą.
Versijos valdymas
Saugojus dokumentus toje pačioje kodų saugykloje kaip ir programinė įranga, lengva valdyti ir stebėti abiejų pakeitimus.
Tu gali naudoti versijų valdymo sistemos kaip Git, kad galėtumėte stebėti dokumentacijos pakeitimus ir, jei reikia, grįžti į ankstesnes versijas. Tai padeda užtikrinti, kad dokumentai būtų tikslūs ir atnaujinami, o jūs galite atsekti ir tikrinti pakeitimus.
Įprastų dokumentų kaip kodo darbo eiga
Įprasti dokumentai kaip kodo darbo eiga apima rašymą, versijų valdymą, kūrimą ir prieglobą:
Rašymo procesas
Rašymo procesas yra pirmasis įprastų dokumentų kaip kodo darbo eigos etapas. Dauguma techniniai rašytojai o dokumentacijos inžinieriai naudoja paprastą MarkDown, AsciiDoc arba HTML. Jie rašo dokumentus naudodami tokius įrankius kaip „GitBook“ ir „Redocly“, kurie užtikrina sklandų procesą.
Dokumentacijos versijos valdymas
Dokumentacija vystosi tobulėjant kodui. Jums reikės sudėtingos versijų valdymo sistemos, pvz., Git, Plastic SCM arba Subversion, kad galėtumėte stebėti dokumentacijos pakeitimus, kad būtų lengviau bendradarbiauti ir sekti versijas.
Dokumentacijos kūrimo procesas
Sukūrimo procesas apima dokumentų apdorojimą ir sudarymą į pristatymo formatus. Tai gali būti HTML, PDF, EPUB ar kiti. Dokumentacijos procesas paprastai palengvinamas naudojant statinius svetainių generatorius, tokius kaip Hugo ir Jekyll.
Priegloba ir dokumentų platinimas
Prieglobos arba platinimo procesas paprastai yra paskutinis dokumentų kaip kodavimo proceso žingsnis. Šis procesas užtikrina, kad dokumentai būtų pristatyti galutiniam vartotojui ir prieinami visoms suinteresuotosioms šalims. Galite naudoti „GitHub“ arba „GitLab“ puslapius arba tinkintą portalą, kad platintumėte savo dokumentus žiniatinklyje.
Galite automatizuoti Go ir Java dokumentaciją naudodami GoDoc ir JavaDoc
Dokumentai, kaip kodo filosofija, keičia techninės dokumentacijos rašymą ir valdymą.
Daugelis programavimo kalbų, įskaitant „Go“ ir „Java“, teikia įrankius, leidžiančius automatizuoti dokumentaciją naudojant kodo komentarus. „Go“ teikia „Godoc“ įrankį, o „Java“ – „JavaDoc“.
