Bij het maken of verbeteren van een applicatie of IT systeem wordt vaak veel documentatie gemaakt. Dit wordt als duur en onnodig ervaren. Door de enorme opkomst van agile, scrum, lean, devops en andere verwante agile ontwikkelmethodieken komt het belang van documentatie onder druk te staan. Maar kunnen we écht met minder documentatie af?

Natuurlijk niemand is gek op het maken van enorme documenten die zelden worden gelezen. Laat staan begrepen. Denk aan analyse studies, uitgebreide use-case beschrijvingen, systeem handleidingen, beheerdocumentatie en niet te vergeten procesdiagrammen waarop op conceptueel niveau bedrijfsfuncties op conceptuele of logische applicatie functies worden afgebeeld. Wetende dat een werkend systeem betekent werkende en geteste broncode, is het natuurlijk niet gek dat de nadruk binnen agile ligt op coderen in plaats van specificeren en beschrijven. Investeringen in IT zijn al duur genoeg en hoe minder overhead hoe beter.

Onzinnige documentatie is duur en change managers, risico managers en architecten hebben de nare neiging om via strakke kwaliteitswaarborgen nog altijd papier te willen zien en goedkeuren voordat systemen of aanpassingen in producten mogen. Binnen de scrum en devops gedachte bots dit. Het proces wordt vertraagd doordat het snel iteratief aanpassen of maken van een systeem tegen procedures en mensen aanloopt die niet volledig in de scrum gedachte mee zijn gegaan.

Kwaliteitswaarborgen zijn altijd handig. Een beetje vertraging vinden we als klant helemaal niet erg. Zeker niet als het om software of systemen gaat waar mensenlevens op het spel staan. Denk bijvoorbeeld aan:

  • Verkeersbegeleidingssystemen (weg, lucht, spoor). Denk aan ERTMS, het nieuw te realiseren beveiligingssysteem voor het spoor.
  • Medische systemen.
  • Communicatie systemen (o.a. meldkamers en defensie systemen)

Maar natuurlijk zijn kwaliteitswaarborgen ook noodzakelijk als het gaat om financiële transactie systemen. Niets zo vervelend als problemen in het betalingsverkeer.

Source code is documentatie. Een goede programmeur heeft een gezonde hekel aan het schrijven van documentatie. Zeker het schrijven van documentatie die niet met de source code mee gecompileerd kan worden. Ondanks de uitgebreide mogelijkheden om source code écht als documentatie te gebruiken (denk aan de vele tools waarmee documentatie over de werking van een programma automatisch gegeneerd kan worden, inclusief testdocumentatie) mist er iets.

Source code is niet universeel. Niet iedereen snapt nu eenmaal C#, C++, .NET, Ruby, Python, Go, Java of een ander dialect. Daarnaast wordt binnen source code zelden vast gelegd:

  • Welke architectuur gebruikt is voordat met realiseren is gestart;
  • Wat de ontwerp beslissingen zijn;
  • Welke requirements input zijn geweest voor de functionaliteit;
  • Wat het beveiligingsontwerp is wat ten grondslag heeft gelegen aan de uiteindelijke code;
  • Wat de kwaliteitseigenschappen zijn van het systeem (denk aan performance, aanpasbaarheid, disaster recovery mogelijkheden etc)

Source code is te wijzigingen,  maar architectuur wijzigingen zijn vaak zeer lastig en erg duur. Architectuur beschrijvingen horen daarom ook over de ‘belangrijkste’ zaken te gaan, beslissingen die niet simpel te wijzigen zijn.

Natuurlijk een gebruikershandleiding op papier zou voor een systeem anno 2015 voltooid verleden tijd moeten zijn. Via een doordacht User Interface ontwerp(UX) zou bediening kinderspel moeten zijn. Aanwijzingen voor gebruikers behoren op maat gegeven worden, afhankelijk van de bewegingen van de gebruiker op het interface scherm.

Universele documentatie is nog altijd documentatie gemaakt om het systeem te ontwerpen en te beheren of in het ergste geval opnieuw te maken. Universele documentatie is informatie die voor iedereen leesbaar en toegankelijk is. In het Nederlands, Engels of andere taal. Liefst met veel afbeeldingen (platen) omdat beelden nét nog wat universeler zijn dan tekst.

Het is gelukkig niet moeilijk om vooraf te bepalen welke documentatie nu écht van belang is. Doordat er veel ervaring is met rampen, missers , hardnekkige IT problemen en uitdagingen bij applicatie uitbreidingen, weten we dit. Architectuur is bij uitstek faciliterend bij het sneller en beter realiseren van IT projecten. Hiermee verdienen architecten zich altijd terug.

universal documentation

Universele documentatie
Tagged on: