Dokumentation er en væsentlig del af softwareudviklingscyklussen. Den forklarer, hvordan man bruger softwaren og kan omfatte brugervejledninger, API-referencer, installationsinstruktioner og udgivelsesbemærkninger.
Automatisering af din dokumentation er den seneste trend, da det kan hjælpe med at spare tid, reducere fejl og sikre konsistens. At holde din dokumentation opdateret og tilgængelig for alle interessenter letter samarbejde og løbende forbedringer.
Docs as code er en tilgang til dokumentationsautomatisering, der behandler teknisk dokumentation som kode.
Hvad er Docs som kode?
Docs as code er en softwareudviklingsfilosofi, der betragter teknisk dokumentation som en form for kode. Det foreslår, at du skal behandle dokumentation med samme strenghed og proces som softwarekode.
Ideen bag docs som kode er at behandle dokumentation som en førsteklasses artefakt af udviklingsprocessen, der integrerer den med softwarens livscyklus. Det betyder, at dokumentation skal behandles som en integreret del af kodebasen. Det betyder at anvende den samme versionskontrol, kontinuerlige integration og testprocesser, som du gør på selve koden.
I en typisk docs as code setup skriver du dokumentationen i almindelige tekstfiler, normalt i et letvægts opmærkningssprog som Markdown, HTML eller reStructuredText. Du gemmer det derefter i samme lager som kildekoden. Dette gør det nemt at administrere og spore ændringer af både software og dokumentation. Det er også med til at sikre, at dokumentationen er opdateret med den seneste version af koden.
Hvorfor du skal bruge Docs som kode
Før docs som kode, blev dokumentation ofte behandlet som adskilt fra koden, oprettet med forskellige værktøjer og processer. Denne løsere tilgang førte ofte til forældet dokumentation og uoverensstemmelser med koden. Du kan udnytte flere fordele ved at bruge docs som kodetilgang.
Forbedret samarbejde
Docs as code muliggør samarbejde mellem udviklere, tekniske skribenter og andre interessenter i udviklingsprocessen. Da kodelageret rummer dokumentationen, er det nemt for forskellige parter at bidrage og foretage ændringer. Dette er med til at sikre, at dokumentationen er nøjagtig, opdateret og omfattende.
En samarbejdstilgang til dokumentation er med til at sikre, at den indeholder al relevant information, og at den nøjagtigt afspejler softwaresystemet som fortolket af alle parter.
Procesautomatisering og tilgængelighed
En anden fordel ved dokumenter som kode er, at det gør det muligt for automatiserede værktøjer at generere og udgive dokumentation. Et byggesystem kan automatisk generere HTML- eller PDF-versioner af dokumentationen fra almindelige tekstfiler til publicering på et websted eller en intern dokumentationsportal. Dette gør dokumentationen tilgængelig for flere interessenter.
Ved at automatisere processen med at generere og udgive dokumentation hjælper docs as code med at reducere den tid og indsats, der kræves for at vedligeholde og udgive dokumentationen. Det giver udviklingsteams mulighed for at fokusere på at forbedre softwaren.
Versionskontrol
Lagring af dokumentation i samme kodelager som softwaren gør det nemt at administrere og spore ændringer til begge.
Du kan bruge versionskontrolsystemer ligesom Git for at spore dokumentationsændringer og vende tilbage til tidligere versioner, hvis det er nødvendigt. Dette er med til at sikre, at dokumentationen er nøjagtig og opdateret, og du kan spore og revidere ændringer.
Den typiske arbejdsgang for dokumenter som kode
Den typiske arbejdsgang for dokumenter som kode omfatter skrivning, versionskontrol, opbygning og hosting:
Skriveprocessen
Skriveprocessen er det første trin i en typisk docs as code workflow. Mest tekniske skribenter og dokumentationsingeniører bruger simple MarkDown, AsciiDoc eller HTML. De skriver dokumentationen ved hjælp af værktøjer som GitBook og Redocly, der sikrer en smidig proces.
Versionskontrol til dokumentation
Dokumentation udvikler sig, efterhånden som kode udvikler sig. Du skal bruge et sofistikeret versionskontrolsystem som Git, Plastic SCM eller Subversion for at spore dokumentationsændringer for lettere samarbejde og versionssporing.
Dokumentationsopbygningsprocessen
Byggeprocessen involverer behandling og kompilering af dokumentationen til dens leveringsformater. Disse kan være HTML, PDF, EPUB eller andre. Dokumentationsprocessen gøres normalt lettere ved at bruge statiske webstedsgeneratorer som Hugo og Jekyll.
Hosting og distribution af dokumentation
Hosting- eller distributionsprocessen er normalt det sidste trin i dokumenterne som en kodningsproces. Denne proces sikrer, at dokumentationen leveres til slutbrugeren og tilgængelig for alle interessenter. Du kan bruge GitHub eller GitLab sider eller en tilpasset portal til at distribuere din dokumentation på nettet.
Du kan automatisere Go- og Java-dokumentation ved hjælp af GoDoc og JavaDoc
Filosofien for dokumenter som kode revolutionerer teknisk dokumentationsskrivning og -styring.
Mange programmeringssprog, herunder Go og Java, giver værktøjer til at automatisere dokumentation ved hjælp af kodekommentarer. Go leverer Godoc-værktøjet, og Java giver JavaDoc.