Technisch schrijven

Doel: Studenten voorbereiden op hun stage en afstuderen. Het schrijven van een afstudeerverslag is nu iets wat ze pas tijdens het afstuderen voor het eerst doen. We moeten ook wat meer standaarden dan enkel de AIM controlekaart geven.

Deze pagina bevat richtlijnen en tips voor technisch schrijven, specifiek gericht op ICT studenten. Deze richtlijnen zijn direct toepasbaar tijdens projecten - bijvoorbeeld bij het schrijven van een Software Guidebook tijdens een project - en helpen je voor te bereiden op je stage en afstuderen. We behandelen hier highlights uit de Google Technical Writing course en andere relevante bronnen, toegespitst op onze ICT studenten.

Inhoudsopgave

De parallelen tussen documenten schrijven en code schrijven

Er zijn opvallende parallelen tussen het schrijven van documenten en het schrijven van code. Beide vereisen structuur, duidelijkheid en een systematische aanpak.

"First make it work; then make it right"

Kent Beck, bekend van Extreme Programming en Test-Driven Development, zei ooit:

"First make it work; then make it right; then make it fast."

Dit principe geldt niet alleen voor code, maar ook voor het schrijven van documenten. Schrijf eerst je tekst, zorg dat de inhoud klopt en de structuur logisch is. Daarna kun je de tekst mooier maken, herschrijven, en verfijnen. Goed schrijven is herschrijven.

Structuur en hiërarchie

Net zoals code structuur heeft (klassen, methoden, functies), hebben documenten ook structuur nodig:

  • Hoofdstukken zijn als modules of klassen - grote logische eenheden
  • Paragrafen zijn als methoden - kleinere functionele eenheden
  • Alinea's zijn als statements - individuele gedachten

Linus Torvalds , degene die het besturingssysteem Linux heeft geschreven - — zei over code structuur:

"If you need more than three levels [...], you're screwed anyway" - Linus Torvalds, Linux kernel coding style

Dit geldt ook voor documenten: gebruik maximaal drie niveaus van koppen (hoofdstuk, paragraaf, subparagraaf). Dieper dan dat wordt het onoverzichtelijk.

Verantwoordelijkheden toewijzen

In code design kennen we principes zoals Single Responsibility Principle (SRP) en GRASP. Bij het schrijven in de actieve vorm wijs je ook verantwoordelijkheden toe aan actoren. Dit maakt teksten duidelijker en beter te begrijpen.

Zie ook de uitgebreide uitleg hierover in de opdrachtbeschrijving onderzoek.

Refactoring

Net zoals je code refactort om deze beter leesbaar en onderhoudbaar te maken, moet je ook teksten herschrijven. De eerste versie is vaak niet de beste versie. Herlees, herschrijf, en verbeter.

Documentstructuur en nummering

Inleiding is Hoofdstuk 1

"De inleiding of introductie is het eerste hoofdstuk van je scriptie." — Scribbr

Sommige documenten zijn wel anders dan een scriptie, maar qua inleiding en nummering moeten HAN documenten deze standaard wel volgen. Het gaat vooral om dat Inleiding een Hoofdstuk is, en Bijlagen en Inhoudsopgave bijvoorbeeld niet, dus die krijgen GEEN hoofdstuknummer en zijn ook meer een soort container waar je zaken in kunt stallen.

Hoofdstukken structureren

Hoofdstukken moeten leesbaar zijn, dus elk hoofdstuk structureer je door het op te delen in subsecties en eventueel subsubsecties met hun eigen semantische kopje, en nummering voor verwijzing.

Leeswijzer

Een eigen leeswijzertje voor het hoofdstuk die deze structuur beschrijft/aankondigt kun je het best schrijven richting het einde, want goed schrijven is herschrijven. Pas als je weet wat er in het hoofdstuk staat, kun je een goede leeswijzer schrijven die de structuur beschrijft.

Actief schrijven (geen lijdende vorm)

De AIM controlekaart geeft aan:

"Je schrijft het document in de actieve vorm. Het bevat nagenoeg geen lijdende zinnen."

Dit is niet alleen een stijlregel, maar heeft ook praktische voordelen:

  • Actieve vorm geeft meer context - je weet wie wat doet
  • Actieve vorm is korter - minder woorden nodig
  • Actieve vorm is duidelijker - verantwoordelijkheden zijn expliciet

Google Technical Writing course benadrukt:

"Passive voice obfuscates your ideas, turning sentences on their head. Passive voice reports action indirectly. Some passive voice sentences omit an actor altogether, which forces the reader to guess the actor's identity. Active voice is generally shorter than passive voice."

Voor ICT studenten is dit extra belangrijk omdat het aansluit bij software design principes: wie is verantwoordelijk voor welke actie? Net zoals in code design waar we verantwoordelijkheden toewijzen aan klassen en methoden.

Tip: Zoek een keer op 'word' of 'worden' in je tekst. Als dit vaker dan 5 keer voorkomt, weet je zeker dat je moet gaan herschrijven en de tekst een stuk korter kan.

Zie voor uitgebreide uitleg en voorbeelden:

Diagrammen altijd voorzien van toelichting

TOELICHTEN = uitLICHTEN en TOEvoegen

Elk diagram, figuur of tabel moet altijd voorzien zijn van een toelichting. Dit betekent:

  1. Een figuurnummer - bijvoorbeeld "Figuur 1"
  2. Een beschrijvende caption - wat toont het diagram?
  3. Verwijzing in de tekst - verwijs naar het figuurnummer, niet naar "hierboven" of "hieronder"
  4. Context - leg uit wat het diagram betekent en waarom het relevant is

Diagrammen en code: een genuanceerde vergelijking

Er is een parallel tussen diagrammen zonder toelichting en code zonder commentaar. Echter, zoals Uncle Bob (Robert C. Martin) aangeeft in zijn verhandeling over de 'Comment' code smell: goede code zou eigenlijk geen commentaar nodig moeten hebben. Als je code commentaar nodig heeft om begrijpelijk te zijn, is dat vaak een teken dat de code zelf niet duidelijk genoeg is - de code moet worden herschreven zodat deze zichzelf documenteert.

Voor diagrammen geldt iets vergelijkbaars: een goed diagram is in principe zelfverklarend. Maar in tegenstelling tot code, waar je de structuur en naamgeving kunt verbeteren, heb je bij diagrammen beperkte mogelijkheden om alles expliciet te maken zonder tekstuele toelichting. Daarom is een caption en contextuele uitleg bij diagrammen altijd nodig - niet als excuus voor een slecht diagram, maar als aanvulling om de lezer te helpen het diagram te interpreteren en te begrijpen waarom het relevant is.

Voorbeeld van goede verwijzing:

"De architectuur van het systeem is weergegeven in Figuur 1. Het diagram toont de drie hoofdlagen: presentatie, business en data."

Niet: "Zoals je hierboven kunt zien..." of "Het plaatje hieronder toont..."

Illustraties effectiever maken

De Google Technical Writing course over Illustrations geeft waardevolle tips om diagrammen en afbeeldingen duidelijker te maken:

Pijlen en annotaties in screenshots

In screenshots kun je direct pijlen toevoegen om belangrijke elementen te markeren. Dit maakt het voor de lezer direct duidelijk waar ze naar moeten kijken.

Notes en annotaties in UML/C4 diagrammen

In UML diagrammen of C4 Container diagrammen kun je notes toevoegen om specifieke aspecten uit te lichten. Dit helpt om complexe relaties of belangrijke beslissingen te verduidelijken.

Kleurcodering voor brown field development

Bij brown field development - het werken met bestaande codebases - is kleurcodering een krachtig middel om onderscheid te maken tussen:

  • Nieuwe componenten/microservices - bijvoorbeeld groen of blauw
  • Bestaande componenten die worden aangepast - bijvoorbeeld geel of oranje
  • Bestaande componenten zonder wijzigingen - bijvoorbeeld grijs

Dit is extra relevant in het nieuwe onderwijs, omdat we nu meer brown field gaan ontwikkelen in plaats van enkel greenfield.

Legenda altijd toevoegen

Zoals Simon Brown aangeeft bij het C4 model: maak altijd netjes een legenda die de kleurcodering en symbolen expliciet maakt. Een legenda voorkomt verwarring en maakt je diagram toegankelijk voor alle lezers.

Voorbeeld van kleurcodering in een C4 Container diagram:

In een C4 diagram kun je bijvoorbeeld:

  • Nieuwe containers weergeven in groen
  • Bestaande containers die worden aangepast in geel
  • Bestaande containers zonder wijzigingen in grijs
  • Een legenda toevoegen die deze kleuren verklaart

Dit maakt direct duidelijk wat nieuw is, wat wordt aangepast, en wat ongewijzigd blijft - essentieel bij brown field development.

Groter is niet altijd beter

Veel beginnende ICT'ers proberen volledig te zijn in hun diagram, en maken een heel groot diagram, die ze dan soms zelfs naar een bijlage verplaatsen omdat het niet 'in het verslag zelf past'. Het is dan echter zaak om tijd te besteden aan hoe je dit grote afbeelding op kan splitsen in meerdere kleinere.

Zoals de Google Technical Writing course over Illustrations aangeeft: "Figure 3. Complex block diagram overwhelm readers." Een te groot diagram overweldigt de lezer en maakt het moeilijk om de essentie te begrijpen.

De essentie in ICT is ook 'probleem decompositie', dus een groot probleem opdelen in deelproblemen. En ook nadenken over hoe je de deeloplossingen die je realiseert vervolgens weer met elkaar laat praten, en samen inderdaad het gehele probleem oplossen. Vandaar ook zowel unit tests als integratie tests (en dus de testpiramide; maar dat terzijde).

Een groot diagram opsplitsen heeft verschillende voordelen:

  • Leesbaarheid - kleinere diagrammen zijn makkelijker te begrijpen
  • Focus - elk diagram kan zich richten op een specifiek aspect
  • Onderhoudbaarheid - kleinere diagrammen zijn makkelijker bij te werken
  • Herbruikbaarheid - deel diagrammen kunnen worden hergebruikt in andere contexten

Denk bijvoorbeeld aan het C4 model: in plaats van één groot diagram met alles, maak je een Context diagram, meerdere Container diagrammen, en Component diagrammen. Elk diagram heeft zijn eigen niveau van detail en doelgroep.

Diagrammen hoeven niet volledig te zijn

Algemene richtlijn/kwaliteitscriterium: Je diagrammen hoeven NIET volledig te zijn, maar moeten goede voorbeelden geven van de meest complexe stukken. De standaard zaken beschrijf je enkel kort in de bijbehorende toelichting.

Voorbeeld: C4 Container diagram met kleurcodering

Bij brown field development kun je een C4 Container diagram maken waarbij:

  • Nieuwe containers in groen worden weergegeven
  • Bestaande containers die worden aangepast in geel
  • Bestaande containers zonder wijzigingen in grijs

Met een duidelijke legenda die deze kleuren verklaart.

Voorbeeld: UML Sequence diagram opsplitsen

Een veelvoorkomend probleem is een UML Sequence diagram dat te groot wordt omdat het zowel externe systeem aanroepen bevat als veel interne details. De oplossing is een combinatie van:

  1. System Sequence diagram - die de interne werking versimpeld weergeeft, volgens Einsteins quote: "Make everything as simple as possible, but not simpler"
  2. Apart sequence diagram - voor bijvoorbeeld enkele objecten uit een gegeven (UML) Class diagram, waar de interactie complexer is en methodes en interfaces uitgedacht moesten worden

Dit sequence diagram vult dan als dynamisch diagram het gegeven klasse diagram (wat een statisch diagram is) aan.

Wat NIET in diagrammen hoeft:

Interne details als getters en setters, of standaard aanroepen van een Controller → Service → Repository maak je geen diagram voor. Maar juist een diagram van een complex voorbeeld, bijvoorbeeld:

  • Een Controller die meerdere Services gebruikt
  • Een Service die meerdere Repositorys spant in een niet-CRUD applicatie en zorgt voor transactionele integriteit

Toelichting beschrijft ook wat NIET in het diagram staat

In de toelichting (TOElichting) bij deze diagrammen moeten ook juist de zaken beschreven worden die NIET in het diagram staan. Je begint wel met wat wel in het diagram staat er UIT te lichten, maar voegt hier dan informatie aan toe.

Voorbeeld: ExpensePro applicatie

Voor een casus over een ExpensePro applicatie, voor het indienen van declaraties door medewerkers van een bedrijf tijdens zakelijke reizen door Europa:

De ExpenseController roept de ExpenseService aan, die gegeven input valideert, en voor het beoordelen van bepaalde declaraties de ExpensePolicyService aanroept voor het beoordelen van declaraties op basis van de regels in het bedrijf en soms ook hierbij eerdere declaraties van de gebruiker in de beslissing betrekt via gebruik van de ExpenseRepository en de ExpensePolicyRepository. De repos worden alleen read acties gedaan, waardoor de ExpensePolicyService geen transactionele integriteit hoeft af te dingen. Dit is anders voor de handmatige goedkeuring van declaraties door admin gebruikers. Daarbij kan een admin een PolicyRule aanpassen, wel zonder update omdat het hier gaat via een nieuwe ExpensePolicyVersion aanmaken met de door gebruiker ingegeven startdatum, zie klassediagram. Maar hierbij ook alle nog openstaande declaraties van afgelopen maand te herwaarderen (en dus te updaten). De LoginController, en UserService en UserRepository hebben een standaard één-op-één verbinding, met relatief weinig logica in de Service. Maar we kiezen toch voor het handhaven van een Service voor toekomstige uitbreidbaarheid en handhaven van de standaard structuur uit de Layered Architecture (zie ADR04).

Belangrijk: Gebruik monospace font (via backticks '`' in Markdown) voor klassennamen en objectnamen, om voor de lezer duidelijk de relatie te leggen tussen documentatie en code.

Optioneel: Domain-Specific Language (DSL) via naamgeving in je domeinmodel

Waarom naamgeving voelt als een DSL

Natuurlijke taal is heel vrij vergeleken met een programmeertaal. Je kunt er van alles mee zeggen, ook dingen die niet kloppen met de werkelijkheid of zelfs intern inconsistent zijn. Deze vrijheid is krachtig in het echte leven, waar de werkelijkheid soms (nog) niet duidelijk is, en we te maken met vage menselijke zaken zoals 'meningen' ;). Maar in een applicatie zoek je juist duidelijkheid. Met zorgvuldige naamgeving van klassen, methodes en properties maak je een kleine taal waarin het níet mogelijk is om semantisch onzinnige combinaties te maken. Je API (de set publieke methodesignatures en type-/propertynamen) vormt zo een mini-DSL voor het domein.

Feitelijk bouw je met de API van je set klassen een taal. NB: met API bedoelen we hier niet per se een web- of REST-API, maar de Application Programmers Interface van een set OO-klassen (denk aan JDBC of Spring Boot MVC). Dit is de verzameling van methodesignatures en eventuele publieke properties (al zijn properties vaak privaat voor encapsulation).

Een paar vuistregels:

  • Kies namen die de ubiquitous language van het domein volgen (Evans).
  • Laat methodesignatures alleen combinaties toestaan die domein-logisch zijn.
  • Vermijd generieke namen als Manager/Util; want die verbergen domeinbegrippen.
  • Een "fluent" syntax kan, mits de zinsdelen domeinlogica afdwingen (Fowler).

Kernidee: de taal van je API moet het makkelijke pad maken voor correcte use-cases, en het moeilijke pad voor onzin of inconsistentie.

Verdieping / literatuur:

  • Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software, hoofdstukken over Ubiquitous Language en modellen.
  • Martin Fowler, Domain-Specific Languages, delen over interne DSL's en fluente interfaces.
  • Vaughn Vernon, Implementing Domain-Driven Design, secties over Bounded Contexts en taalafspraken.

Highlights uit Google Technical Writing course

De Google Technical Writing course bevat veel waardevolle richtlijnen voor technisch schrijven. Hieronder enkele highlights specifiek relevant voor ICT studenten:

1. Voorkom bijvoeglijke naamwoorden en bijwoorden

"...adjectives and adverbs can make technical documentation sound dangerously like marketing material." - Google Technical Writing (2023)

Schrijf je een technische tekst voor een technische doelgroep, dan is het gebruik van heel veel bijvoeglijke naamwoorden of bijwoorden NIET gepast. ChatGPT heeft bijvoorbeeld de neiging om "jubelende" teksten te schrijven:

  • ❌ "deze essentiële tool ..."
  • ❌ "dit is voor DevOps-ontwikkelaars absoluut onmisbaar"
  • ❌ "tool X fungeert als cruciale pijler"
  • ❌ "tool X is een uiterst waardevol instrument"

Dit is marketing taal, niet technische documentatie. Wees objectief en feitelijk.

2. Duidelijke zinnen

  • Korte zinnen - één idee per zin
  • Eenvoudige woorden - gebruik geen moeilijke woorden als eenvoudige woorden volstaan
  • Concrete taal - vermijd abstracte termen waar mogelijk

3. Actieve vorm (zie boven)

Zie de sectie Actief schrijven hierboven.

4. Doelgroepgericht schrijven

Schrijf voor je doelgroep. Voor ICT studenten betekent dit vaak:

  • Je klasgenoten (peers)
  • Buitenstaanders met hetzelfde kennisniveau (ICT'ers)
  • Soms: niet-technische stakeholders

Pas je taalgebruik aan op je doelgroep, maar blijf technisch accuraat.

5. Structuur en organisatie

  • Logische volgorde - presenteer informatie in een logische volgorde
  • Duidelijke koppen - koppen moeten duidelijk maken wat er in de sectie staat
  • Consistente terminologie - gebruik dezelfde termen voor hetzelfde concept

Bullet lijsten in technische teksten

Gebruik in technische teksten bullet lijsten. En waar handig sub bullet lijsten. Maar leidt ze altijd even in, met een zin.

Google: "when writing, seek opportunities to convert prose into lists." — Google Technical Writing - Lists and Tables

Je ziet dat PlantUML van bullets dus ook zomaar een (work break down) boom van kan maken.

"If a table cell holds more than two sentences, ask yourself whether that information belongs in some other format." — Google Technical Writing - Lists and Tables

Markdown gebruiken

Markdown is een veelgebruikte opmaaktaal voor technische documentatie. Praktische voordelen:

  • Documentatie staat naast je broncode in dezelfde repo → versiebeheer en PR-review lopen samen.
  • Bij een commit of feature branch pas je code én documentatie tegelijk aan.
  • Prima voor developer-doelgroep; voor niet-devs kun je via Pandoc exporteren als PDF of Word.
  • Previews en linting zijn makkelijk (mdBook, GitHub preview) zodat je ziet hoe het eruitziet vóór publicatie.
  • In combinatie met diagrams-as-code (PlantUML, mermaid) versioneer je ook je diagrammen in Git, met diffs, PR-review en near-WYSIWYG previews op GitHub/GitLab.

Niet ideaal voor rijke lay-out of DTP-achtige eindopmaak; gebruik dan liever Word/Google Docs/LaTeX. De Google Technical Writing course heeft ook een sectie over Markdown die de moeite waard is om te lezen.

Belangrijke Markdown conventies voor technisch schrijven

  • Monospace font voor code - gebruik backticks (`) voor klassennamen, methodenamen, variabelen, etc. Dit maakt duidelijk wat code is en wat gewone tekst
  • Koppen - gebruik koppen voor structuur (niet te diep, maximaal 3 niveaus)
  • Lijsten - gebruik lijsten voor opsommingen
  • Links - gebruik Markdown links in plaats van lange URL's in de tekst

Voorbeeld van monospace gebruik:

De ExpenseController gebruikt de ExpenseService om declaraties te valideren. De ExpenseService roept vervolgens de ExpensePolicyService aan voor het beoordelen van declaraties.

Dit maakt duidelijk welke delen code zijn en welke gewone tekst.

APA-bronvermelding

Doel van bronvermelding bij ICT

Hoewel je bij het lezen van algemene documenten vaak leest dat bronreferenties het doel hebben om plagiaat te voorkomen, is het bij ICT ook vooral de bedoeling om met referenties aan te tonen dat je daadwerkelijk zelf hebt verdiept in externe bronnen. Je toont aan dat je dergelijke vaak algemenere theorie ook juist kan toepassen en koppelen op de opdracht waar jij zelf mee bezig bent. Zodat je daadwerkelijk 'applied science', dus toegepaste wetenschap aan het doen bent.

Basisregels voor APA-bronvermelding

Vergeet verder niet om bij APA zowel voor elke gebruikte bron:

  1. de bron goed op te nemen in de Bronnen lijst, met juiste vorm afhankelijk of het een webbron is of niet
  2. en ook een referentie naar deze bron in je tekst op te nemen met een quote of parafrase.

De referentie tussen haakjes:

De referentie, het stuk tussen haakjes met auteurs- of organisatienaam en een jaartal staat hierbij tussen haakjes. En dat betekent dat je de zin waarin deze staat ook moet kunnen lezen als je dit stuk tussen haakjes weglaat. De bron kan dus niet onderwerp of lijdend voorwerp in de zin zijn.

Goed (alternatieve manier):

Google (2022) benadrukt dat actieve vorm korter is dan passieve vorm.

Deze versie is ook correct omdat je het jaartal tussen haakjes kunt weglaten en nog steeds een logische zin hebt: "Google benadrukt dat actieve vorm korter is dan passieve vorm."

Fout (bron wordt onderwerp):

(Google, 2022) benadrukt dat de actieve vorm korter is dan passieve vorm.

Hier wordt "Google" het onderwerp van de zin, wat niet mag volgens APA-regels.

Citeren vs parafraseren in het AI-tijdperk

In het huidige 'AI assisted' tijdperk is het verder wel handig om te neigen naar eerder letterlijk quoten van het materiaal. Want parafraseren zijn LLM's veel te goed in. En hierbij is het ook veel minder makkelijk om te checken of je daadwerkelijk goed aansluit bij een gelezen bron. Of dat je in je argumentatie wat stappen overslaat, of drogredenen opvoert.

Als er nog redeneerstappen zitten tussen de quote uit de bron en je eigen idee of conclusie, dan moet je deze in je tekst ook duidelijk maken.

Tekst moet op zichzelf leesbaar zijn

Het is essentieel dat je de lezer niet dwingt om de referentie ook daadwerkelijk te lezen en erbij te zoeken. Je stuk moet op zichzelf leesbaar en begrijpelijk zijn. De referenties zijn alleen bedoeld voor de lezer om makkelijk te kunnen controleren of het wel klopt. En om verdere optionele informatie erbij te zoeken.

Geen lange URL's in de tekst

Het heeft dus ook geen zin om gewoon naar de voorpagina van een website te verwijzen, bijvoorbeeld naar de Spring Boot landingspagina. Dan kun je deze domeinnaam gewoon opnemen in je tekst zelf zonder APA. Maar als je een argumentatie wil ondersteunen, zoek dan een blog op Spring Boot website op of andere site, of andere meer deeplink op.

Zet verder geen lange URL's in je tekst, maar gebruik APA. Je document moet op zichzelf leesbaar zijn, er is al veel te veel afleiding in de huidige wereld.

Voorkeur voor bronnen met auteur en datum

Geef ook de voorkeur aan bronnen waar daadwerkelijk een auteursnaam of tenminste organisatienaam op staat. En een datum van schrijven. Zodat niet al je bronnen z.d. worden.

Maak verder duidelijke onderscheid tussen 'medium' en 'organisatie', want bijvoorbeeld 'medium.com', maar ook stackoverflow.com en YouTube.com zijn een medium en is niet de organisatienaam die verantwoordelijk is voor de inhoud. Bij APA moet je de organisatie noemen.

Voorkeur voor erkende auteurs

Geef verder weer de voorkeur aan schrijvers die ook in lesstof voorkomen of in het vakgebied hoog aangeschreven staan, zoals Martin Fowler, Bob Martin (Uncle Bob), Kent Beck, etc. als optie.

Toepasselijkheid van 'Technisch schrijven' op Plan van Aanpak

Aan het begin van een project moeten studenten ook een Plan van Aanpak (ook wel 'Projectplan' geheten) schrijven als groep. Dit is minder een technisch document, maar meer een zakelijk document. Toch gelden veel van dezelfde regels uit deze pagina ook voor een Plan van Aanpak.

Doelgroepgericht schrijven blijft belangrijk

Hoewel een Plan van Aanpak een zakelijker karakter heeft dan technische documentatie, blijft doelgroepgericht schrijven het belangrijkste. Je schrijft voor:

  • De opdrachtgever (vaak niet-technisch)
  • Projectbegeleiders (technisch, maar ook procesmatig geïnteresseerd)
  • Teamgenoten (technisch)

Pas je taalgebruik aan: je hoeft de lezer minder lastig te vallen met technische details, maar moet wel duidelijk en specifiek zijn over wat je gaat doen.

Specifiek maken en vooronderzoek doen

In ICT Projectplannen is het zaak om het document al zo specifiek mogelijk te maken. Dit betekent:

  • Doe het nodige vooronderzoek - onderzoek de technologieën, frameworks en tools die je gaat gebruiken voordat je het plan schrijft
  • Geen algemene zaken beschrijven - vermijd vage beschrijvingen zoals "we gaan een moderne webapplicatie bouwen"
  • Wees concreet - beschrijf specifieke technologieën, frameworks en aanpakken

Onderscheid maken tussen projectresultaten en randvoorwaarden

Maak duidelijk onderscheid tussen:

  • Projectresultaten en kwaliteitscriteria - wat lever je op en hoe meet je of het goed is?
  • Randvoorwaarden - wat zijn de beperkingen en eisen waar je mee moet werken?
  • Uitgesloten zaken - wat valt expliciet buiten de scope?

Risico's met uitwijkstrategieën en tegenmaatregelen

Voor elk geïdentificeerd risico moet je beschrijven:

  • Het risico - wat kan er misgaan?
  • De impact - wat zijn de gevolgen als het risico optreedt?
  • Tegenmaatregelen - wat ga je doen om het risico te voorkomen of te beperken?
  • Uitwijkstrategie - wat ga je doen als het risico toch optreedt?

Dit maakt je plan realistisch en toont aan dat je hebt nagedacht over mogelijke problemen.

Verwijzing naar Roel Grit

Voor uitgebreide richtlijnen over het schrijven van projectplannen, zie het boek van Roel Grit over projectmanagement. Dit boek behandelt de structuur en inhoud van projectplannen in detail.

Bronnen

Last change: 2025-12-05