Softwaredocumentatie

Softwaredocumentatie is geschreven tekst, vaak vergezeld van illustraties, die software of een informaticatoepassing beschrijft. Het omvat alle geschreven documenten en materialen die te maken hebben met de ontwikkeling en het gebruik van een softwareproduct. Documentatie is een essentieel onderdeel van software engineering en is cruciaal voor zowel de ontwikkelaars als de eindgebruikers van de software.

Softwaredocumentatie
Deelgebied van	Software engineering
Onderwerp	Het vastleggen en overdragen van kennis over software
Gerelateerde gebieden	Technische communicatie, Kennisbeheer, User experience design

De opmaak van dit artikel is nog niet in overeenstemming met de conventies van Wikipedia. Mogelijk is ook de spelling of het taalgebruik niet in orde. Men wordt uitgenodigd deze pagina aan te passen.
Opgegeven reden: Veel vette tekst, te veel opsommingen in plaats van een lopend verhaal

---

Doel van documentatie

Softwaredocumentatie dient verschillende doelen gedurende de levenscyclus van een softwareproduct:

• Communicatie en Kennisoverdracht: Het faciliteert de communicatie tussen teamleden (ontwikkelaars, testers, projectmanagers) en belanghebbenden. Nieuwe teamleden kunnen zich sneller inwerken.
• Onderhoud en Beheer: Goede documentatie is onmisbaar voor het onderhouden, aanpassen en uitbreiden van software. Het helpt ontwikkelaars om de code en architectuur te begrijpen, zelfs jaren nadat deze is geschreven.
• Gebruikersondersteuning: Voor eindgebruikers biedt het instructies, handleidingen en naslaginformatie, wat het aantal supportvragen kan verminderen.
• Kwaliteitsborging: Documentatie zoals eisen- en ontwerpspecificaties vormt de basis voor het testen van de software en het valideren dat het product aan de gestelde eisen voldoet.
• Archivering: Het dient als een archief van het project, waarin beslissingen, ontwerpoverwegingen en de evolutie van het product worden vastgelegd.

Soorten softwaredocumentatie

Softwaredocumentatie kan grofweg worden onderverdeeld in twee hoofdcategorieën: productdocumentatie en procesdocumentatie.^[1]

Productdocumentatie

Productdocumentatie beschrijft het product dat wordt ontwikkeld en geeft instructies over hoe het te gebruiken. Het wordt verder onderverdeeld in:

Systeemdocumentatie

Dit type documentatie beschrijft het systeem zelf en de onderdelen ervan. Het is voornamelijk bedoeld voor ontwikkelaars en onderhoudsteams. Voorbeelden zijn:

• Eisen- en specificatiedocumenten: Formele documenten die beschrijven wat de software moet kunnen (functionele en niet-functionele eisen).
• Architectuur- en Ontwerpdocumentatie: Beschrijft de algehele structuur van de software, de gebruikte componenten, hun interfaces en het gedrag. Diagrammen zoals UML-diagrammen worden hier vaak gebruikt.
• Broncodedocumentatie: Commentaar direct in de broncode, bedoeld om de logica, het doel en het gebruik van specifieke codeblokken, functies en klassen uit te leggen.
• API-documentatie: Essentieel voor software die een API aanbiedt. Het beschrijft de beschikbare functies, klassen, return types en argumenten, zodat andere ontwikkelaars de API correct kunnen gebruiken.

Gebruikersdocumentatie

Dit type documentatie is gericht op de eindgebruikers van de software. Het doel is om hen te helpen de software effectief te gebruiken. Voorbeelden zijn:

• Installatiehandleidingen: Stapsgewijze instructies voor het installeren en configureren van de software.
• Gebruikershandleidingen: Een uitgebreide gids die alle functies van de software beschrijft.
• Tutorials en 'Getting Started'-gidsen: Begeleiden nieuwe gebruikers bij hun eerste stappen met de software om een specifiek doel te bereiken.
• Veelgestelde vragen (FAQ): Een lijst met antwoorden op veelvoorkomende vragen van gebruikers.
• Release notes: Een overzicht van veranderingen, nieuwe functies en opgeloste bugs in een nieuwe versie van de software.

Procesdocumentatie

Procesdocumentatie heeft betrekking op het ontwikkelingsproces zelf. Het legt de gebeurtenissen en beslissingen gedurende het project vast. Voorbeelden zijn:

• Projectplannen, schattingen en planningen.
• Testplannen en testrapporten.
• Notulen van vergaderingen en overzichten van beslissingen.
• Standaarden en richtlijnen die binnen het project worden gehanteerd.

Standaarden en methoden

Er bestaan diverse standaarden voor het opstellen van softwaredocumentatie. Een bekende reeks is de ISO/IEC/IEEE 26512-standaard, die richtlijnen geeft voor de documentatie voor softwaregebruikers.

Moderne softwareontwikkeling maakt vaak gebruik van de "documentation-as-code"-benadering. Hierbij wordt documentatie behandeld als broncode: het wordt geschreven in platte-tekstformaten (zoals Markdown of reStructuredText), beheerd in een versiebeheersysteem (zoals Git), en automatisch gepubliceerd als onderdeel van het bouwproces (CI/CD).^[2]

Hulpmiddelen

Er is een breed scala aan tools beschikbaar om het schrijven en beheren van softwaredocumentatie te ondersteunen:

• Documentatiegeneratoren: Tools die API-documentatie direct uit commentaar in de broncode genereren. Bekende voorbeelden zijn Javadoc (voor Java), Doxygen (voor o.a. C++, C, Python) en Sphinx (voor Python).
• Wiki-software: Systemen zoals Confluence en MediaWiki (de software achter Wikipedia) worden vaak gebruikt voor interne, collaboratieve documentatie.
• Statische site generatoren: Tools zoals MkDocs, Hugo en Jekyll worden veel gebruikt voor de "documentation-as-code"-aanpak om strakke, doorzoekbare documentatiewebsites te creëren.
• Diagramtools: Software zoals Microsoft Visio, Draw.io (nu diagrams.net) of PlantUML (voor het genereren van diagrammen uit code) wordt gebruikt om architectuur en processen te visualiseren.