Documenteer de code

Goed gedocumenteerde broncode helpt mensen te begrijpen wat de broncode doet en hoe de broncode moet worden gebruikt. Documentatie is onmisbaar voor mensen om de codebase te gaan gebruiken en eraan bij te dragen.

Vereisten

• Alle functionaliteit van de codebase, zowel het beleid als de broncode, MOET worden beschreven in een taal die duidelijk te begrijpen is voor degenen die het doel van de codebase moeten begrijpen.

• De documentatie van de codebase MOET een beschrijving bevatten van hoe de software moet worden geïnstalleerd en uitgevoerd.

• De documentatie van de codebase MOET voorbeelden bevatten die de belangrijkste functionaliteit demonstreren.

• De documentatie van de codebase ZOU een algemene beschrijving MOETEN bevatten die duidelijk te begrijpen is voor een breed publiek van belanghebbenden, zoals het algemeen publiek en journalisten.

• De documentatie van de codebase ZOU een paragraaf MOETEN bevatten die beschrijft hoe een zelfstandige versie van de broncode kan worden geïnstalleerd en uitgevoerd, inclusief, indien nodig, een testdataset.

• De documentatie van de codebase ZOU voorbeelden MOETEN bevatten van alle functionaliteit.

• De documentatie ZOU de belangrijkste componenten of modules van de codebase en hun relaties MOETEN beschrijven, bijvoorbeeld als een hoog-over architectuurdiagram.

• Er ZOUDEN continue integratietests MOETEN worden uitgevoerd om de kwaliteit van de documentatie te controleren.

Hoe te testen

• Controleer of andere belanghebbenden, professionals van andere publieke organisaties en het brede publiek de documentatie duidelijk en begrijpelijk vinden.

• Controleer of de documentatie beschrijft hoe de broncode moet worden geïnstalleerd en uitgevoerd.

• Controleer of de documentatie voorbeelden bevat van de belangrijkste functionaliteit.

• Vraag mensen uit het brede publiek en journalisten of ze de algemene beschrijving begrijpen.

• Controleer of de instructies voor het installeren en uitvoeren van een zelfstandige versie van de broncode resulteren in een werkend systeem.

• Controleer of alle gedocumenteerde functionaliteit een voorbeeld bevat.

• Controleer of de documentatie een hoog-over architectuurdiagram of iets dergelijks bevat.

• Controleer of de kwaliteit van de documentatie deel uitmaakt van de integratietests, bijvoorbeeld of de documentatie correct is gegenereerd en of verwijzingen en afbeeldingen zijn getest.

Beleidsmakers in de publieke sector: wat je moet doen

• Kijk regelmatig of begrijpelijk is hoe de niet-beleidscode in de codebase is gewijzigd.

• Geef feedback over hoe de documentatie van niet-beleidscode duidelijker gemaakt kan worden.

Managers: wat je moet doen

• Probeer de codebase te gebruiken, zodat je feedback kan bijdragen aan een betere documentatie van het beleid en de broncode. Is de huidige documentatie bijvoorbeeld voldoende om een manager bij een andere publieke organisatie te overtuigen om deze codebase te gebruiken?

• Zorg ervoor dat je de beleid- en broncode evenals de documentatie begrijpt.

Ontwikkelaars en ontwerpers: wat je moet doen

• Controleer regelmatig hoe de niet-broncode in de codebase is gewijzigd.

• Geef feedback over hoe de documentatie van de niet-broncode duidelijker gemaakt kan worden.

Meer informatie

• Documentation guide door Write the Docs.