Schrijven van IT-documentatie

Voor opdrachtgever Ictivity mocht ik in augustus een dag naar het team Interne services van SURFsara, de landelijke organisatie voor ICT-voorzieningen voor het wetenschappelijk onderwijs en onderzoek, op het Science Park in Amsterdam. SURFsara verleent diensten (rekenkracht, supersnel datatransport, dataverwerking en -analyse) aan haar klanten, de instellingen voor wetenschappelijk onderwijs en onderzoek. Bij SURFsara hebben ze dus echt grote computers staan (die heb ik niet gezien).  

Het team Interne services zorgt dat de medewerkers van SURFsara qua IT-voorzieningen hun werk kunnen doen. De helpdesk, zeg maar. Bij Interne services moeten ze van alle markten thuis zijn: de medewerkers hebben ieder hun eigen specialisaties. Oplossingen die zij vinden, zijn niet per definitie helder voor hun directe collega's. Dus goed documenteren is nodig – maar dat schiet er nogal eens bij in. Omdat er altijd problemen met prioriteit opgelost moeten worden. En omdat documenteren minder interessant is.

Maar ook: omdat er geen goede uitgangspunten zijn. En daarom werd ik uitgenodigd. Zodat het team en ik daarover samen konden nadenken. Want binnenkort neemt het een nieuw systeem in gebruik, en dan graag meteen goed.

Daarop wilde ik me terdege voorbereiden. Al heb ik zelf wel gebruikershandleidingen, online helppagina's en commerciële teksten over software geschreven, erover gelezen/geleerd had ik nog nooit. Uiteindelijk vond ik twee boeken, beide geschreven vanuit de praktijk, bij gebrek aan 'theorie'. De aandachtspunten die ik daaruit destilleerde, nam ik op in mijn PowerPoint.

Ik heb lang niet alles gepresenteerd aan het team. Dat hoefde ook niet. Wel heb ik – zoals in iedere schrijftraining – hen gewezen op 'doel en lezer', het belang van een inleiding, en goed en consequent structureren. En nog het een en ander uit de boeken.

Mede door de vasthoudendheid van een teamlid stond er aan het eind van de dag een basisstructuur die onderscheid maakte tussen procedures en topics over services (beschrijvingen). Voor beide typen documentatie stond er een basisstramien. Bovendien de aanzet tot een stijlgids. Een goede basis voor het nieuwe systeem en een mooie opbrengst voor één dag!