Technische documentatie¶

Je houdt technische documentatie bij over je (web)applicatie en relationele database. Hierin beschrijf je hoe de software is opgebouwd, welke keuzes je hebt gemaakt en hoe anderen de code kunnen begrijpen en onderhouden volgens geldende standaarden. Dit product past bij de leeruitkomst Software: onderhoudbare software en technische documentatie.

Technische documentatie helpt je team en anderen om snel te begrijpen hoe het systeem werkt: architectuur, belangrijke modules, configuratie, hoe je de applicatie draait en test. Het kan bestaan uit een README, aparte documenten per onderdeel, of een gecentraliseerd technisch overzicht. Code comments en GitLab zijn aanvullend; dit product gaat over de overkoepelende, leesbare uitleg.

Kwaliteitsindicatoren¶

Bij het waarderen van dit product zal er worden gekeken naar de volgende kwaliteitsindicatoren:

De documentatie is een op zichzelf staand overzicht met een duidelijke introductie en doel.
De opbouw van de applicatie en/of database is beschreven (structuur, belangrijke onderdelen).
Technische keuzes zijn toegelicht (waarom deze techniek, framework, aanpak).
Er is beschreven hoe anderen de code kunnen begrijpen, bouwen en draaien (bijv. installatie, configuratie).
De documentatie sluit aan bij geldende standaarden en conventies van de opleiding of het project.
Er zijn verwijzingen naar de code in GitLab waar van toepassing.
De documentatie is actueel en consistent met de huidige codebase.

Template¶

Om technische documentatie te schrijven, kan je gebruik maken van de volgende template:

# Technische documentatie: [applicatie / project]

Korte introductie: wat doet de applicatie en voor wie is deze documentatie bedoeld?

## Overzicht architectuur

Hoe is de applicatie opgebouwd? (front-end, back-end, database, eventueel diagram)

## Technische keuzes

Welke technieken, frameworks en standaarden zijn gebruikt en waarom?

## Structuur van de codebase

Waar staat wat? (mappen, belangrijke bestanden, conventies)

## Opstarten en configuratie

Hoe installeer en start je de applicatie? Welke configuratie is nodig (env, database, poorten)?

## Database

Korte beschrijving van de relationele database: doel, belangrijkste tabellen, relaties. Eventueel verwijzing naar ERD of apart datastructuur-document.

## Bronnen

Eventueel: documentatie van gebruikte frameworks, standaarden, referenties naar GitLab.