Dokumentation är en viktig del av mjukvaruutvecklingscykeln. Den förklarar hur man använder programvaran och kan inkludera användarguider, API-referenser, installationsinstruktioner och utgåvan.
Att automatisera din dokumentation är den senaste trenden eftersom det kan hjälpa till att spara tid, minska fel och säkerställa konsekvens. Att hålla din dokumentation uppdaterad och tillgänglig för alla intressenter underlättar samarbete och ständiga förbättringar.
Dokument som kod är ett tillvägagångssätt för dokumentationsautomatisering som behandlar teknisk dokumentation som kod.
Vad är Dokument som kod?
Docs as code är en mjukvaruutvecklingsfilosofi som ser teknisk dokumentation som en form av kod. Det föreslår att du bör behandla dokumentation med samma rigoritet och process som programvarukod.
Tanken bakom docs som kod är att behandla dokumentation som en förstklassig artefakt av utvecklingsprocessen, och integrera den med mjukvarans livscykel. Detta innebär att man behandlar dokumentation som en integrerad del av kodbasen. Det innebär att tillämpa samma versionskontroll, kontinuerliga integration och testprocesser som du gör på själva koden.
I en typisk docs as code setup skriver du dokumentationen i vanliga textfiler, vanligtvis i ett lättviktigt märkningsspråk som Markdown, HTML eller reStructuredText. Du lagrar det sedan i samma arkiv som källkoden. Detta gör det enkelt att hantera och spåra ändringar i både programvara och dokumentation. Det hjälper också till att säkerställa att dokumentationen är uppdaterad med den senaste versionen av koden.
Varför du bör använda dokument som kod
Innan dokument som kod behandlades dokumentation ofta som separat från koden, skapad med olika verktyg och processer. Detta lösare tillvägagångssätt ledde ofta till föråldrad dokumentation och inkonsekvenser med koden. Du kan dra nytta av flera fördelar genom att använda dokumenten som en kod.
Förbättrat samarbete
Dokument som kod möjliggör samarbete mellan utvecklare, tekniska skribenter och andra intressenter i utvecklingsprocessen. Eftersom kodarkivet innehåller dokumentationen är det lätt för olika parter att bidra och göra ändringar. Detta hjälper till att säkerställa att dokumentationen är korrekt, uppdaterad och heltäckande.
En samarbetsstrategi för dokumentation hjälper till att säkerställa att den innehåller all relevant information och att den korrekt återspeglar mjukvarusystemet som tolkas av alla parter.
Processautomation och tillgänglighet
En annan fördel med dokument som kod är att det gör det möjligt för automatiserade verktyg att generera och publicera dokumentation. Ett byggsystem kan automatiskt generera HTML- eller PDF-versioner av dokumentationen från vanliga textfiler för publicering på en webbplats eller en intern dokumentationsportal. Detta gör dokumentationen tillgänglig för fler intressenter.
Genom att automatisera processen att generera och publicera dokumentation hjälper docs as code till att minska den tid och ansträngning som krävs för att underhålla och publicera dokumentationen. Det tillåter utvecklingsteam att fokusera på att förbättra programvaran.
Versionskontroll
Att lagra dokumentation i samma kodlager som programvaran gör det enkelt att hantera och spåra ändringar av båda.
Du kan använda versionskontrollsystem som Git för att spåra dokumentationsändringar och återgå till tidigare versioner om det behövs. Detta hjälper till att säkerställa att dokumentationen är korrekt och uppdaterad, och du kan spåra och granska ändringar.
Det typiska arbetsflödet för dokument som kod
Det typiska arbetsflödet för dokument som kod omfattar skrivning, versionskontroll, byggande och värdskap:
Skrivprocessen
Skrivprocessen är det första steget i ett typiskt arbetsflöde för dokument som kod. Mest tekniska skribenter och dokumentationsingenjörer använder enkla MarkDown, AsciiDoc eller HTML. De skriver dokumentationen med hjälp av verktyg som GitBook och Redocly som säkerställer en smidig process.
Versionskontroll för dokumentation
Dokumentation utvecklas i takt med att kod utvecklas. Du behöver ett sofistikerat versionskontrollsystem som Git, Plastic SCM eller Subversion för att spåra dokumentationsändringar för enklare samarbete och versionsspårning.
Dokumentationsprocessen
Byggprocessen innebär att bearbeta och sammanställa dokumentationen till dess leveransformat. Dessa kan vara HTML, PDF, EPUB eller andra. Dokumentationsprocessen görs vanligtvis enklare med statiska webbplatsgeneratorer som Hugo och Jekyll.
Hosta och distribuera dokumentation
Hosting- eller distributionsprocessen är vanligtvis det sista steget i dokumenten som en kodningsprocess. Denna process säkerställer att dokumentationen levereras till slutanvändaren och tillgänglig för alla intressenter. Du kan använda GitHub eller GitLab-sidor eller en anpassad portal för att distribuera din dokumentation på webben.
Du kan automatisera Go- och Java-dokumentation med GoDoc och JavaDoc
Filosofin för docs as code revolutionerar skrivning och hantering av teknisk dokumentation.
Många programmeringsspråk, inklusive Go och Java, tillhandahåller verktyg för att automatisera dokumentation med hjälp av kodkommentarer. Go tillhandahåller Godoc-verktyget och Java tillhandahåller JavaDoc.