Beheer

Software-ontwikkeling
TL;DR

TL;DR

Hoewel techneuten niet van documentatie houden, is er toch meer gedocumenteerd dan je zou denken.

12 november 2020

Een tijdje geleden werd ik gevraagd om een 'managementdashboard' te maken. Een van de key performance indicatoren die daarop moesten verschijnen, ging over het aantal ernstige verstoringen en de gemiddeld benodigde tijd om die op te lossen.

U snapt wel wat ik als eerste vroeg. Welke soorten incidenten kennen jullie, wat zijn hun karakteristieken en hoe zie ik die in jullie servicemanagementpakket terug? Wat is de standaardwerkwijze bij incident management en welke fasen onderkennen jullie? Oeps, dat was niet gedocumenteerd. En nee, een dump van een handjevol keuzelijsten geldt niet als 'documentatie'.

Het is werkelijk godgeklaagd. Nog nooit had men de beschikking over zo veel hulpmiddelen om zaken vast te leggen en nog nooit werd er zo beroerd gebruik van gemaakt. Ik moet de eerste workflow nog tegenkomen waarin staat “werk de documentatie bij”. Ja, ik weet dat “alles op een share staat”. Ik weet dat ik “op sleutelwoorden” kan zoeken. Maar ik weet niet of dit gedigitaliseerde equivalent van de winkel van malle pietje volledig of actueel is. Want er is niets wat dat garandeert en niemand die zich er verantwoordelijk voor voelt.

Ik moet de eerste workflow nog tegenkomen waarin staat “werk de documentatie bij”

Techneuten houden niet van documentatie. Toch is er meer gedocumenteerd dan je zou verwachten. Elk internetprotocol is gedocumenteerd. Elke bestandsoort is gedocumenteerd. Elke programmeertaal is gedocumenteerd. Zelfs de overwegingen die daarbij een rol speelden, zijn netjes gedocumenteerd. Het taalgebruik als “moet”, “mag” en “zou moeten” is gedocumenteerd.

Het probleem is echter dat documenteren zo’n ondankbaar werk is. Want met het toenemen van de dikte van een boekwerk neemt ook de neiging toe om dat juist niet te gebruiken. Zo kwam ik in een forum een bijdrage van een gebruiker tegen die bij hoog en laag volhield dat er een fout in zijn compiler zat. Maar er was niks mis met de compiler. Die deed precies wat de internationale standaard voorschreef. De vraag was of de documentatie was geraadpleegd. Nee, natuurlijk niet. Het leek de man “alleen maar logisch dat het zo zou werken”.

Raad eens welk antwoord hij kreeg. Ik zal een hint geven. Een andere afkorting.

Magazine AG Connect

Dit artikel is ook gepubliceerd in het magazine van AG Connect (novembernummer, 2020). Wil je alle artikelen uit dit nummer lezen, klik dan hier voor de inhoudsopgave.

Reactie toevoegen
2
Reacties
Hans Bezemer 13 november 2020 15:12

@Atilla Vigh
Het leuke van jouw reacties vind ik altijd, dat ze een nuance toevoegen aan mijn column. Met een aantal zaken ben ik het eens - en met een aantal niet.

Ten eerste, bedenk dat een stuk software een hoop "gebruikers" kent. Degene, die het gebruikt, vaak in samenhang met zijn werk. Degene, die het installeert en technisch beheert, de functioneel beheerder en de ontwikkelaar. Dat levert het volgende beeld op: een "user guide" (waar de kale werking wordt uitgelegd), daaruit voorkomend de "werkinstructies", die de "user guide" vertaalt naar de procedures binnen het werkproces, de "installation guide" voor de beheerder, tesamen met kale beheersinstructies (bv. common errors - and how to fix them), standaard functioneel onderhoud (bv. toegang geven, stamtabel onderhoud) voor functioneel beheerders, technische documentatie, zoals architectuur, modules, ERM, API, etc, voor ontwikkelaars.

Dat is nogal een rijtje! Als jij dat kunt samenvatten in een Powerpoint ga ik graag bij je in de leer. Voor een proces is het niet anders. Je hebt je standaarden (bv. voor klassificatie) te documenteren, je procesontwerp, je organisatie (met taken en bevoegdheden), je procedures, je werkinstructies - en je connecties met andere processen. In mijn wereld kom je dan uit op een paar vette boekwerken.

Bij onderzoeken is het hetzelfde. Sure, je kunt de uitkomsten in een Q&D PowerPoint zetten. Maar daar zit een risico aan. Als je niet stap voor stap documenteert:
(1) Wat was het doel van het onderzoek;
(2) Hoe heb je het ingericht en waarom heb je het zo ingericht (dat je [1] inderdaad kunt vervullen);
(3) Hoe je het hebt uitgevoerd conform [2];
(4) Wat de rauwe resultaten waren;
(5) Op welke manier je [4] verwerkt hebt en welke keuzes je hebt gemaakt;
(6) Dat [5] leidde tot deze conclusies, zodanig dat deze antwoord op [1] gaven.
Dan geef ik je op een briefje, dat die onduidelijkheid tegen je gebruikt gaat worden op het moment dat er problemen zijn - immers, je bent toch weg.
Derhalve is mijn standpunt dan ook, zorg dat je je zaakjes goed gedocumenteerd hebt - die PPT kan altijd nog.

Tenslotte, er zijn verschillende technieken om uitgebreide documentatie toch toegankelijk te houden, bv. door deze op te delen naar de verschillende "stakeholders", bv. gebruikers, beheerders, ontwikkelaars, management, experts, etc.

Documentatie maken in echt een VAK. Helaas zijn er maar weinigen, die die kunst echt verstaan. Borland is er bv. een. Net als Mark Williams Company. Of de Bull BOS docs. Maar het rijtje is helaas kort.

Atilla Vigh 12 november 2020 12:15

RTFM....maar goed dat is wel een flauw antwoord voor een gebruiker die een ander uitkomst van de compiler verwachtte. Er is zat software in omloop waar de documentatie die er dan wel is in sync is met de werking, maar in alle redelijkheid niet doet wat het zou moeten doen.
Je opmerking "Het probleem is echter dat documenteren zo’n ondankbaar werk is. Want met het toenemen van de dikte van een boekwerk neemt ook de neiging toe om dat juist niet te gebruiken" houdt me al geruime tijd bezig. In de praktijk klopt dit wel niet. Niet leuk vinden en vooral te maken met dat het dikke boekwerken worden. De vraag rijst of het wel hele dikke boekwerken moeten worden. Een tweede probleem is dat er gedacht wordt dat maar 1 persoon de documentatie zou moeten opleveren.
In kom nog uit een tijd dat we vuistdikke rapporten schreven, en omdat niemand die las, gingen we over op PowerPoint slides en ik merk zo nu en dan in de dagelijkse praktijk dat men multimediale presentaties (compleet met motion graphics en voice-over).
De gehele organisatie waar middelen en oplossingen samen komen zal er gekozen moeten worden hoe men e.e.a. vastlegt tijdens de verandering en in welke vorm en welke collega's daarin dan een rol spelen. Wat daarbij belangrijk is, is om de beroemde nut- en noodzaak vraag goed te onderbouwen. In het algemeen schrijf je documentatie niet voor jezelf (hoewel, ik zou het wel doen!), maar vooral voor anderen. De uitdrukking is niet voor niets "kennis zit in de hoofden".