Dokumentācija ir būtiska programmatūras izstrādes cikla sastāvdaļa. Tajā ir paskaidrots, kā lietot programmatūru, un tajā var iekļaut lietotāja rokasgrāmatas, API atsauces, instalēšanas instrukcijas un izlaiduma piezīmes.
Dokumentācijas automatizācija ir jaunākā tendence, jo tā var palīdzēt ietaupīt laiku, samazināt kļūdas un nodrošināt konsekvenci. Dokumentācijas atjaunināšana un pieejamība visām ieinteresētajām personām atvieglo sadarbību un pastāvīgus uzlabojumus.
Dokumenti kā kods ir pieeja dokumentācijas automatizācijai, kas tehnisko dokumentāciju uzskata par kodu.
Kas ir dokumenti kā kods?
Dokumenti kā kods ir programmatūras izstrādes filozofija, kas tehnisko dokumentāciju uzskata par koda formu. Tas liek domāt, ka dokumentācijai ir jābūt tādai pašai stingrai un jāapstrādā kā programmatūras kodam.
Dokumentu kā koda ideja ir uzskatīt dokumentāciju kā pirmšķirīgu izstrādes procesa artefaktu, integrējot to programmatūras dzīves ciklā. Tas nozīmē, ka dokumentācija tiek uzskatīta par neatņemamu kodu bāzes sastāvdaļu. Tas nozīmē, ka tam jāpiemēro tāda pati versijas kontrole, nepārtraukta integrācija un testēšanas procesi, ko veicat pašam kodam.
Parastos dokumentos kā koda iestatīšana dokumentācija tiek rakstīta vienkārša teksta failos, parasti šādā formātā viegla iezīmēšanas valoda, piemēram, Markdown, HTML vai reStructuredText. Pēc tam jūs to saglabājat tajā pašā repozitorijā, kurā atrodas avota kods. Tādējādi ir viegli pārvaldīt un izsekot gan programmatūras, gan dokumentācijas izmaiņām. Tas arī palīdz nodrošināt, ka dokumentācija ir atjaunināta ar jaunāko koda versiju.
Kāpēc jums vajadzētu izmantot dokumentus kā kodu
Pirms dokumentiem kā koda dokumentācija bieži tika uzskatīta par atsevišķu no koda, kas tika izveidota ar dažādiem rīkiem un procesiem. Šī brīvāka pieeja bieži noveda pie novecojušas dokumentācijas un neatbilstības kodam. Varat izmantot vairākas priekšrocības, izmantojot dokumentus kā kodu pieeju.
Uzlabota sadarbība
Dokumenti kā kods nodrošina sadarbību starp izstrādātājiem, tehniskajiem autoriem un citām izstrādes procesā ieinteresētajām personām. Tā kā kodu krātuvē atrodas dokumentācija, dažādām pusēm ir viegli sniegt ieguldījumu un veikt izmaiņas. Tas palīdz nodrošināt, ka dokumentācija ir precīza, atjaunināta un visaptveroša.
Sadarbības pieeja dokumentācijai palīdz nodrošināt, ka tajā ir iekļauta visa atbilstošā informācija un ka tā precīzi atspoguļo programmatūras sistēmu, kā to interpretē visas puses.
Procesu automatizācija un pieejamība
Vēl viena dokumentu kā koda priekšrocība ir tā, ka tas nodrošina automatizētus rīkus dokumentācijas ģenerēšanai un publicēšanai. Būvsistēma var automātiski ģenerēt dokumentācijas HTML vai PDF versijas no vienkārša teksta failiem publicēšanai vietnē vai iekšējā dokumentācijas portālā. Tādējādi dokumentācija ir pieejama lielākam skaitam ieinteresēto personu.
Automatizējot dokumentācijas ģenerēšanas un publicēšanas procesu, dokumenti kā kods palīdz samazināt laiku un pūles, kas nepieciešamas dokumentācijas uzturēšanai un publicēšanai. Tas ļauj izstrādes komandām koncentrēties uz programmatūras uzlabošanu.
Versiju kontrole
Dokumentācijas glabāšana tajā pašā kodu krātuvē, kurā atrodas programmatūra, ļauj viegli pārvaldīt un izsekot abām izmaiņām.
Tu vari izmantot versiju kontroles sistēmas piemēram, Git, lai izsekotu dokumentācijas izmaiņām un vajadzības gadījumā atgrieztos pie iepriekšējām versijām. Tas palīdz nodrošināt, ka dokumentācija ir precīza un atjaunināta, un jūs varat izsekot un pārbaudīt izmaiņas.
Tipiskā dokumentu kā koda darbplūsma
Tipiski dokumenti kā koda darbplūsma ietver rakstīšanu, versiju kontroli, veidošanu un mitināšanu:
Rakstīšanas process
Rakstīšanas process ir tipisku dokumentu kā koda darbplūsmas pirmais posms. Lielākā daļa tehniskie rakstnieki un dokumentācijas inženieri izmanto vienkāršu MarkDown, AsciiDoc vai HTML. Viņi raksta dokumentāciju, izmantojot tādus rīkus kā GitBook un Redocly, kas nodrošina vienmērīgu procesu.
Dokumentācijas versiju kontrole
Dokumentācija attīstās, attīstoties kodam. Jums būs nepieciešama sarežģīta versiju kontroles sistēma, piemēram, Git, Plastic SCM vai Subversion, lai izsekotu dokumentācijas izmaiņām un atvieglotu sadarbību un versiju izsekošanu.
Dokumentācijas veidošanas process
Būvēšanas process ietver dokumentācijas apstrādi un apkopošanu tās piegādes formātos. Tie var būt HTML, PDF, EPUB vai citi. Dokumentācijas process parasti tiek atvieglots, izmantojot statiskos vietņu ģeneratorus, piemēram, Hugo un Jekyll.
Dokumentācijas mitināšana un izplatīšana
Hostings vai izplatīšanas process parasti ir pēdējais dokumentu kā kodēšanas process. Šis process nodrošina, ka dokumentācija tiek piegādāta gala lietotājam un ir pieejama visām ieinteresētajām personām. Varat izmantot GitHub vai GitLab lapas vai pielāgotu portālu, lai izplatītu savu dokumentāciju tīmeklī.
Varat automatizēt Go un Java dokumentāciju, izmantojot GoDoc un JavaDoc
Dokumenti kā koda filozofija rada apvērsumu tehniskās dokumentācijas rakstīšanā un pārvaldībā.
Daudzas programmēšanas valodas, tostarp Go un Java, nodrošina rīkus dokumentācijas automatizācijai, izmantojot koda komentārus. Go nodrošina Godoc rīku, un Java nodrošina JavaDoc.
