Dokumentasjon er en viktig del av programvareutviklingssyklusen. Den forklarer hvordan du bruker programvaren og kan inkludere brukerveiledninger, API-referanser, installasjonsinstruksjoner og versjonsmerknader.
Automatisering av dokumentasjonen er den siste trenden siden det kan bidra til å spare tid, redusere feil og sikre konsistens. Å holde dokumentasjonen oppdatert og tilgjengelig for alle interessenter letter samarbeid og kontinuerlig forbedring.
Dokumenter som kode er en tilnærming til dokumentasjonsautomatisering som behandler teknisk dokumentasjon som kode.
Hva er Dokumenter som kode?
Docs as code er en programvareutviklingsfilosofi som ser på teknisk dokumentasjon som en form for kode. Det foreslår at du bør behandle dokumentasjon med samme strenghet og prosess som programvarekode.
Ideen bak docs som kode er å behandle dokumentasjon som en førsteklasses artefakt av utviklingsprosessen, og integrere den med programvarens livssyklus. Dette betyr å behandle dokumentasjon som en integrert del av kodebasen. Det betyr å bruke den samme versjonskontrollen, kontinuerlige integrasjonen og testprosessene som du gjør på selve koden.
I et typisk docs as code-oppsett skriver du dokumentasjonen i vanlige tekstfiler, vanligvis i et lett merkespråk som Markdown, HTML eller reStructuredText. Du lagrer den deretter i samme depot som kildekoden. Dette gjør det enkelt å administrere og spore endringer i både programvare og dokumentasjon. Det bidrar også til å sikre at dokumentasjonen er oppdatert med siste versjon av koden.
Hvorfor du bør bruke dokumenter som kode
Før dokumenter som kode, ble dokumentasjon ofte behandlet som atskilt fra koden, laget med forskjellige verktøy og prosesser. Denne løsere tilnærmingen førte ofte til utdatert dokumentasjon og inkonsistens med koden. Du kan utnytte flere fordeler ved å ta i bruk dokumentene som kodetilnærming.
Forbedret samarbeid
Dokumenter som kode muliggjør samarbeid mellom utviklere, tekniske skribenter og andre interessenter i utviklingsprosessen. Siden kodelageret inneholder dokumentasjonen, er det enkelt for ulike parter å bidra og gjøre endringer. Dette bidrar til å sikre at dokumentasjonen er nøyaktig, oppdatert og omfattende.
En samarbeidende tilnærming til dokumentasjon bidrar til å sikre at den inkluderer all relevant informasjon og at den nøyaktig gjenspeiler programvaresystemet slik det tolkes av alle parter.
Prosessautomatisering og tilgjengelighet
En annen fordel med dokumenter som kode er at den lar automatiserte verktøy generere og publisere dokumentasjon. Et byggesystem kan automatisk generere HTML- eller PDF-versjoner av dokumentasjonen fra vanlige tekstfiler for publisering til et nettsted eller en intern dokumentasjonsportal. Dette gjør dokumentasjonen tilgjengelig for flere interessenter.
Ved å automatisere prosessen med å generere og publisere dokumentasjon, bidrar docs as code til å redusere tiden og innsatsen som kreves for å vedlikeholde og publisere dokumentasjonen. Det lar utviklingsteam fokusere på å forbedre programvaren.
Versjonskontroll
Lagring av dokumentasjon i samme kodelager som programvaren gjør det enkelt å administrere og spore endringer i begge.
Du kan bruke versjonskontrollsystemer som Git for å spore dokumentasjonsendringer og gå tilbake til tidligere versjoner om nødvendig. Dette bidrar til å sikre at dokumentasjonen er nøyaktig og oppdatert, og du kan spore og revidere endringer.
Den typiske arbeidsflyten for dokumenter som kode
Den typiske arbeidsflyten for dokumenter som kode omfatter skriving, versjonskontroll, bygging og hosting:
Skriveprosessen
Skriveprosessen er det første trinnet i en typisk dokument- som kodearbeidsflyt. Mest tekniske forfattere og dokumentasjonsingeniører bruker enkle MarkDown, AsciiDoc eller HTML. De skriver dokumentasjonen ved hjelp av verktøy som GitBook og Redocly som sikrer en jevn prosess.
Versjonskontroll for dokumentasjon
Dokumentasjon utvikler seg etter hvert som kode utvikler seg. Du trenger et sofistikert versjonskontrollsystem som Git, Plastic SCM eller Subversion for å spore dokumentasjonsendringer for enklere samarbeid og versjonssporing.
Dokumentasjonsbyggingsprosessen
Byggeprosessen involverer bearbeiding og kompilering av dokumentasjonen til leveringsformatene. Disse kan være HTML, PDF, EPUB eller andre. Dokumentasjonsprosessen gjøres vanligvis enklere ved å bruke statiske nettstedsgeneratorer som Hugo og Jekyll.
Hosting og distribusjon av dokumentasjon
Verts- eller distribusjonsprosessen er vanligvis det siste trinnet i dokumentene som en kodeprosess. Denne prosessen sikrer at dokumentasjonen leveres til sluttbrukeren og tilgjengelig for alle interessenter. Du kan bruke GitHub- eller GitLab-sider eller en tilpasset portal for å distribuere dokumentasjonen din på nettet.
Du kan automatisere Go- og Java-dokumentasjon ved å bruke GoDoc og JavaDoc
Filosofien for dokumentene som kode revolusjonerer teknisk dokumentasjonsskriving og -administrasjon.
Mange programmeringsspråk, inkludert Go og Java, gir verktøy for å automatisere dokumentasjon ved hjelp av kodekommentarer. Go gir Godoc-verktøyet, og Java gir JavaDoc.
