Documentatie is een essentieel onderdeel van de softwareontwikkelingscyclus. Het legt uit hoe de software moet worden gebruikt en kan gebruikershandleidingen, API-referenties, installatie-instructies en release-opmerkingen bevatten.
Het automatiseren van uw documentatie is de nieuwste trend, omdat het u kan helpen tijd te besparen, fouten te verminderen en consistentie te waarborgen. Door uw documentatie up-to-date en toegankelijk te houden voor alle belanghebbenden, wordt samenwerking en continue verbetering vergemakkelijkt.
Documenten als code is een benadering van documentatie-automatisering die technische documentatie als code behandelt.
Wat is Documenten als code?
Documenten als code is een softwareontwikkelingsfilosofie die technische documentatie beschouwt als een vorm van code. Het suggereert dat u documentatie met dezelfde strengheid en hetzelfde proces moet behandelen als softwarecode.
Het idee achter documenten als code is om documentatie te behandelen als een eersteklas artefact van het ontwikkelingsproces, door het te integreren met de softwarelevenscyclus. Dit betekent dat documentatie wordt behandeld als een integraal onderdeel van de codebase. Het betekent dat je hetzelfde versiebeheer, continue integratie en testprocessen toepast als op de code zelf.
In een typische docs as code-setup schrijft u de documentatie in platte tekstbestanden, meestal in een lichtgewicht opmaaktaal zoals Markdown, HTML of reStructuredText. Je slaat het vervolgens op in dezelfde repository als de broncode. Dit maakt het gemakkelijk om wijzigingen in zowel software als documentatie te beheren en bij te houden. Het helpt ook ervoor te zorgen dat de documentatie up-to-date is met de nieuwste versie van de code.
Waarom u Documenten als code zou moeten gebruiken
Voordat documenten als code bestonden, werd documentatie vaak los van de code behandeld, gemaakt met verschillende tools en processen. Deze lossere aanpak leidde vaak tot verouderde documentatie en inconsistenties met de code. U kunt verschillende voordelen benutten door de documenten als codebenadering te gebruiken.
Verbeterde samenwerking
Docs as code maakt samenwerking mogelijk tussen ontwikkelaars, technische schrijvers en andere belanghebbenden in het ontwikkelingsproces. Omdat de coderepository de documentatie bevat, is het voor verschillende partijen gemakkelijk om bij te dragen en wijzigingen aan te brengen. Dit helpt ervoor te zorgen dat de documentatie nauwkeurig, up-to-date en volledig is.
Een gezamenlijke benadering van documentatie helpt ervoor te zorgen dat deze alle relevante informatie bevat en dat deze het softwaresysteem nauwkeurig weergeeft zoals geïnterpreteerd door alle partijen.
Procesautomatisering en toegankelijkheid
Een ander voordeel van documenten als code is dat het geautomatiseerde tools mogelijk maakt om documentatie te genereren en te publiceren. Een bouwsysteem kan automatisch HTML- of PDF-versies van de documentatie genereren uit platte tekstbestanden voor publicatie op een website of een intern documentatieportaal. Dit maakt de documentatie toegankelijk voor meer belanghebbenden.
Door het proces van het genereren en publiceren van documentatie te automatiseren, helpt docs as code de tijd en moeite te verminderen die nodig zijn om de documentatie te onderhouden en te publiceren. Het stelt ontwikkelingsteams in staat zich te concentreren op het verbeteren van de software.
Versiebeheer
Door documentatie op te slaan in dezelfde coderepository als de software, is het eenvoudig om wijzigingen in beide te beheren en bij te houden.
Je kunt gebruiken versie controle systemen zoals Git om wijzigingen in de documentatie bij te houden en indien nodig terug te keren naar vorige versies. Dit helpt ervoor te zorgen dat de documentatie nauwkeurig en up-to-date is en dat u wijzigingen kunt traceren en controleren.
De typische documenten als codeworkflow
De typische workflow voor documenten als code omvat schrijven, versiebeheer, bouwen en hosten:
Het schrijfproces
Het schrijfproces is de eerste fase van een typische document als code-workflow. Meest technische schrijvers en documentatie-engineers gebruiken eenvoudige MarkDown, AsciiDoc of HTML. Ze schrijven de documentatie met behulp van tools zoals GitBook en Redocly die zorgen voor een soepel proces.
Versiebeheer voor documentatie
Documentatie evolueert naarmate code evolueert. U hebt een geavanceerd versiebeheersysteem nodig, zoals Git, Plastic SCM of Subversion, om wijzigingen in de documentatie bij te houden, zodat u gemakkelijker kunt samenwerken en versies kunt bijhouden.
Het documentatiebouwproces
Het bouwproces omvat het verwerken en samenstellen van de documentatie in de leveringsformaten. Dit kunnen HTML, PDF, EPUB of andere zijn. Het documentatieproces wordt meestal gemakkelijker gemaakt met behulp van statische site-generatoren zoals Hugo en Jekyll.
Documentatie hosten en distribueren
Het hosting- of distributieproces is meestal de laatste stap van de documenten als coderingsproces. Dit proces zorgt ervoor dat de documentatie wordt afgeleverd bij de eindgebruiker en beschikbaar is voor alle belanghebbenden. U kunt GitHub- of GitLab-pagina's of een aangepaste portal gebruiken om uw documentatie op internet te verspreiden.
U kunt Go- en Java-documentatie automatiseren met GoDoc en JavaDoc
De docs as code-filosofie zorgt voor een revolutie in het schrijven en beheren van technische documentatie.
Veel programmeertalen, waaronder Go en Java, bieden hulpmiddelen om documentatie te automatiseren met behulp van codecommentaar. Go biedt de Godoc-tool en Java biedt JavaDoc.