Software documentatie? Dat hebben wij toch helemaal niet nodig!

Basic Design, Detailed Design, Functional Specification Document, Software Design Documents, Design Base: allemaal mooie termen om een benaming te geven aan een document dat de wensen en eisen van de software vastlegt. Deze wensen kunnen zowel van externe- als interne klanten komen. Extern kan bijvoorbeeld zijn dat de machine met een bepaalde snelheid moet kunnen functioneren. Intern kan zijn dat er binnen een organisatie gewerkt wordt met een software standaard.

Met de start van een project stappen we vaak vol enthousiasme in de documentatie. Het zo goed mogelijk formuleren van de eisen van de klant. Je hebt dan ook verschillende klanten: Degenen die enige voorkennis dragen van software engineering en degenen die hier totaal geen kennis van hebben. Belangrijk is dan dat de betrokken partijen gezamenlijk begrijpen wat het doel is.

Waarom?

Bedenk altijd goed voor wie en wat we de documentatie opstellen. Over het algemeen hebben de software engineers een hekel aan de documentatie, anders waren we immers wel technical document writers geworden. Des al niet te min beginnen we altijd heel enthousiast, maar bij het onderhoud van het document is het dan weer minder omdat we vaak al weer met één been in het volgende project staan.

Voor wie of wat doen we het dan:

  • De minimale eis van de klant. Dit kan zowel intern dan wel extern zijn. Uiteindelijk is dit natuurlijk een zakelijke beslissing en de klant die betaalt, bepaalt dan ook waar zijn geld aan gespendeerd wordt.
  • Om de standaard communicatiekanalen te ondersteunen. Helemaal nu we meer vanuit huis werken, is het een tool om bepaalde kennis via documentatie over te dragen.
  • Waarborgen van kennis. Personen komen en gaan, dus ook de kennis die zij meedragen. Het blijft altijd een uitdaging om kennis op papier te zetten. Software zonder enige softwaredocumentatie ter ondersteuning neigt vaak al snel naar niet onderhoudbare software. De kennis en kunde is dan vastgelegd in de software, maar krijgt een slechte legacy wanneer het niet goed staat gedocumenteerd. In Agile termen: primair doel is om werkende software op te leveren, secundaire doel is ondersteunende documentatie voor het gebruik, ondersteuning en onderhoud van de software.
  • Verificatie / audit. Software wordt geverifieerd door een test team. De test engineers moeten aan de hand van requirement lijsten en use cases de software testen en beoordelen. Zonder documentatie is altijd alles goed volgens de developer. Mocht je de software ontwikkelen onder een specifieke norm of guideline, dan is de documentatie ter ondersteuning voor de audit.
  • Plan Do Check Act. Het is vaak handig om je ideeën op papier te zetten. Dit werkt verhelderend en je kunt vaak al vroegtijdig problemen detecteren. In je hoofd kan het vaak logisch en makkelijk lijken, maar de uitvoering laat vaak wat anders zien. Zo kun je ook makkelijker te werk gaan met je sparringpartner.

Ondanks dat het bovenstaande heel logisch klinkt, moet je altijd blijven bedenken wat het doel is van de documentatie. In bureaucratisch geneuzel heeft echt niemand zin.

 Traditionele documentatie schrijven.

In de waterval en V-model wordt veel tijd gespendeerd aan het opzetten van de documentatie. Dit is dan ook een vast onderdeel binnen het waterval / V-model. Deze modellen hebben dan ook te maken met procedures. De volgende kunnen hier gevonden worden:

  • De documentatie is verplicht en vaak een milestone op de agenda. Het werk in het project vordert vaak ook alleen maar als de documentatie af is. Van Concept design, Basic design, Detailed design tot aan alle test en afname documenten.
  • De documentatie ondergaat een review procedure, waarbij een “checked” en “approved” door verschillende personen wordt uitgevoerd.
  • Gestandaardiseerde documentatietemplates worden toegepast.
  • Aanpassingen in de documentatie later in het project gaan volgens procedures. Voor kleine aanpassingen kan dit veel tijd gaan kosten om bij te houden.
  • Bij grotere projecten ontstaan er ook veel documenten. Om versiebeheer goed te kunnen faciliteren is een goed proces of systeem gewenst. Denk aan database software en/of document control.

Hoe een software specificatie document er in basis uit kan zien:

  1. Inleiding van het document
  2. Systeem
    2.1 Sub-systeem A

    • Introduction
    • Sub-systeem I/O
    • Requirements
      Het definiëren van de requirements kan heel goed met de MoSCoW-methode:

      • Must haves, moeten in het eind resultaat
      • Should haves, zijn zeer gewenst maar kan wel functioneren zonder
      • Could haves, mocht er tijd over zijn dan kunnen deze geïmplementeerd worden
      • Won’t haves, deze eizen komen niet aan bod bij dit project. Mogelijk bij een volgend project.
    • Detailed requirements of functions
      Uitleg van een requirement vertaald naar functies voor de softwareDetailed requirements of command chain and error / alarm / interlock handling

            2.2  Sub-systeem B

            2.3 Sub-systeem C

  1. Netwerk
    • Introduction
    • Communication requirements
    • Netwerk overview
  2. Application software
  3. Parameters / settings

Dit is een summiere opzet. Afhankelijk van de level detaillering kan er meer of minder in.

 User interface

Of dit nu via een Scada gebeurt of een “simpele” HMI, het is belangrijk om visueel te maken wat er opgeleverd moet worden. Je kunt dit via top-down of bottom-up doen: eerst de user interface schetsen en dan de software functie beschrijven of eerst de software functies beschrijven en dan de user interface erbij verzinnen.

Hiervoor gebruik ik MS Visio, een handige tool om snel wat op te kunnen schetsen. Je kunt je eigen standaard al hier inbrengen. Dus je kleuren pallet, je druk knoppen, I/O, etc, etc. Wanneer je je eigen standaard klaar hebt staan kun je heel snel al een basis opzet maken. Maak je visual niet scherm-breed, dan kun je bijvoorbeeld nog met tekstballonnen commentaar geven op de functie van het knopje. Hierdoor weet de stakeholder van het project redelijk snel wat hij kan verwachten. Ook werkt dit handig voor software engineers, ze kunnen redelijk snel en zonder na te denken een opzet maken van de interface.

Agile software documentatie schrijven

Binnen Agile ligt de focus niet per definitie op het schrijven van de documentatie maar meer op de ‘definition of done’ en de toegevoegde waarde voor de stakeholders. Agile is zo gebouwd dat het ontmoedigt om aan randzaken te werken en direct toegevoegde waarde te leveren voor het project/de klant.

De Agile werkt met de volgende fundatie:

  • Individuen en interacties boven processen en tools
  • Werkende software boven uitgebreide documentatie
  • Klantensamenwerking boven contractonderhandeling
  • Reageren op omschakeling boven werken volgens plan

Documenteren volgens de Agile werkwijze komt met een aantal basisprincipes:

  • Just barely good enough (JBGE)
    Zorg ervoor dat de relevante informatie erin staat onduidelijkheid te voorkomen. Onthoud ook dat documentatie altijd onderhouden moet worden. Wanneer het een ‘Lite’ document is, makkelijk te bergrijpen is, is het ook makkelijk te onderhouden en aan te passen later in het project.
  • Just In Time (JIT)
    Documenteer zo laat mogelijk – net op tijd. Het is niet logisch om maanden van te voren de informatie te documenteren, zodat wanneer je het echt nodig hebt, de informatie veranderd kan zijn. Dus documenteer wanneer je het moet hebben.
  • Houd de informatie op één plek en maak het beschikbaar voor anderen.
    Documentatie is alleen bruikbaar en van nut wanneer het toegankelijk is. Maak gebruik van een cloud-server om het beschikbaar te stellen voor je teamleden. Wat interessant is om op te zetten, is een (interne) Wiki.
  • Werk samen in het team.
    Het maken en onderhouden van de documentatie doe je samen, in teamverband. Zorg dat je elkaar binnen het team hierop aanspoort. Bekijk eens hoe de Wikipedia werkt.

Om bovenstaande goed te laten functioneren, moet er goed worden gekeken naar een (Agile) documentatietool.  De tool moet minimaal flexibel, transparant en makkelijk te bereiken zijn. Anders wordt er toch geen gebruik van gemaakt.

Wanneer moet je dan deze documenten schrijven?

Doordat er met iteratief wordt gewerkt met Agile, wordt er niet eindeloos tijd besteed aan functionele ontwerpen. Het idee is om de documentatie zo eenvoudig mogelijk te houden, met name in de beginstadium van het project. Maar welk moment is het juist om je tijd te investeren in het documenteren.

Er zijn twee mogelijke oplossingen:

  • Zo laat mogelijk
    Wacht totdat je genoeg informatie bij elkaar hebt verzameld om dit tot een document te kneden. Doe dit dan wel net voordat je het toe gaat passen. Je kunt zelf voor sommige documentatie zo lang wachten totdat het volledig uitgekristalliseerd is voordat je het vast legt op papier. Bijvoorbeeld support documentatie, system overviews.
  • Constant documenteren
    Dit ligt in lijn van de Agile gedachtegoed. Je schrijft stukken documentatie die meteen op te leveren zijn en gebruikt kunnen worden, je schrijft dus requirements voor een functie. Direct na het documenteren maak je de bijbehorende code. Als nu blijkt uit testen en checks dat het niet helemaal voldoet, pas je het document aan en direct daarna de code. Het nadeel is dat requirments kunnen veranderen tijdens het ontwerpproces, dat betekend ook dat je constant documentatie bij moet gaan houden. Dit schept onnodig werk en in de praktijk wordt dus vaak de ‘zo laat mogelijk’ methode toegepast. Het neemt niet weg dat de developer iets moet hebben om mee te werken, dan wel dat de tester moet kunnen valideren.

Wat voor documenten dan?

Wie de lezer gaat zijn wordt bepaalt door het soort documenten en hoe deze geschreven zijn. Er moeten documenten komen waarbij hoger management, project management, klant, ontwikkelaars, testers, onderhoud en de operationele afdeling de juiste informatie uit kunnen halen.

Voorbeelden:

  • Product vision:
    • Wie: hoger management, klant, project management
    • Wat: In basis wat het product gaat zijn of in gaat houden. Verwachte kosten – baten, risico’s, benodigde resources, geplande milestones.
    • Hoe: Houd het kort en krachtig. Opsommen kan hierbij helpen
  • Project overview:
    • Wie: ontwikkelaars, testers, onderhoud, operationele afdeling
    • Wat: een opsomming van alle kritische informatie van het project. De technologie en tools die gebruikt worden binnen het project
    • Hoe: Houd het kort en krachtig. Dit is ook een document dat bij wordt gehouden door het project heen. Wordt ook gebruikt als een nieuweling het project intreed.
  • Design decisions:
    • Wie: ontwikkelaars, testers, project managers
    • Wat: Een overview van kritische ontwikkel beslissingen. Dit kan bijvoorbeeld over architectuur, ontwerp en/of functie zijn.
    • Hoe: Documenteren wordt door het project heen gedaan. Dit kan door overviews zijn of zelfs source code dat wordt vast gelegd.
  • Operationele documentation
    • Wie: Operationele afdeling
    • Wat: Een beschrijving waar het systeem operationeel betrokken bij is. Procedures, inbedrijf name procedures, probleemoplossingen
    • Hoe: Bekijk wat er al wordt toegepast binnen deze afdeling. Documentatie is vaak al beknopt.
  • Requirements documentation
    • Wie: Ontwikkelaars, Testers, Onderhoud, Klant, Gebruikers
    • Wat: een overview wat het systeem doet, use cases, user interface, prototypes
    • Hoe: Excel lijst met requirements, Visio voor de user interface. Wat er standaard wordt gebruikt binnen het team
  • System documentation
    • Wie: Onderhoudm ontwikkelaars
    • Wat: High level requirements, technische architectuur, System overview
      Dit behoud dat kritische informatie wordt vast gelegd wanneer het ontwikkel team het project verlaat
    • Hoe: Zie requirements documentation
    • User documentation
      • Wie: klanten, management
      • Wat: user manuals, support guides
      • Hoe: houd het kort en bondig. Makkelijk te gebruiken document.

Ja we hebben het nodig!

We hebben het allemaal waarschijnlijk wel eens een keer mee gemaakt: Iemand die het project verliet en/of slecht had gedocumenteerd. Of zelfs het bedrijf verlaat. Slechte communicatie tussen jouw en de klant. Dan is het natuurlijk duidelijk dat we het een en ander moeten vastleggen om een product te kunnen maken en onderhouden. Net zoals bij de projectmanagement methode is er geen goed of slecht. Éen aanpak moet wel draagvlak hebben. Het v-model principe kan goed werken, met name als je een product levert waarbij al genoeg voorkennis is van de subsystemen. Dit kan zijn omdat de losse subsystemen eerder zijn gemaakt. Een functioneel ontwerp is dan het best van A tot Z te maken, ook voordat er geprogrammeerd wordt. Met genoeg voorkennis is dit goed mogelijk. De Agile aanpak werkt dan ook lekker in een echt R&D project. Het oplossen van een probleem maar de route er naar toe nog niet goed in beeld. Voor beide aanpakken is het handig om te weten hoe software opgebouwd gaat worden, wordt er een standaard gebruikt, component basis, hoe wordt er omgegaan met datastromen. Dit bepaald al enigszins wat er in de documentatie komt.