De documentatie van de IT-specialist: welke documentatie?

Het maakt niet uit bij welke klant ik kom, regelmatig komt het gespreksonderwerp op de documentatie van de IT-specialist. Of eigenlijk meer: het gebrek aan documentatie. Want mensen, het is een feit dat heel veel IT-specialisten moeite hebben met documenteren. En vaak is het niet zo dat zij niet willen documenteren, het kost simpelweg teveel moeite, want: een goede IT-specialist is lui!

Voor de manager

Manager, mag ik je feliciteren? Je hebt goede IT-specialisten in dienst want ze zijn lui! En proberen dus alles weg te automatiseren wat maar enigszins kan.

Kort gezegd is de gemiddelde IT-specialist zijn of haar hele werkweek bezig om deze luiheid te optimaliseren. Zitten je techneuten met hun benen over elkaar, staan ze op hun gemak (!) bij de koffieautomaat: wees er blij mee, zij hebben hun zaakjes voor elkaar en alles functioneert! Want afmeten hoe actief een techneut is doe je niet aan de techneut zelf maar aan zijn of haar computers: als hun computers hard aan het werk zijn, dan zijn zij dat ook 😀. Nu alleen nog dat puntje van die documentatie, maar dat heeft zo z'n redenen.

Voor de IT-specialist/techneut

Mag ik jou ook feliciteren? Een luie techneut is een goede techneut! Je probeert alles weg te automatiseren wat je ook maar enigszins ge-script krijgt. En documentatie is moeilijk te scripten en de aangereikte tools (zoals uitgebreide Officepakketten) zijn vaak te lastig in gebruik. Voor ons dan. Punt.

Want zeg nou zelf: Word met zijn templates en autocorrectie, je moet nadenken over de opmaak op plekken waar je dat niet wilt (wat is een kop (hoofdstuk), enz.), terwijl op andere plekken het systeem voor jou nadenkt over de opmaak, terwijl je dit juist niet wilt. Je zet je ertoe, je gaat documenteren en knipt-en-plakt vervolgens een aantal command-line commando's vanuit je terminal in het document en..... aaaaiii - je commando's worden automatisch voorzien van hoofdletters aan het begin!

Dat is dus niet de bedoeling. Hoe moet je hiermee ooit een goede werkinstructie schrijven? Dit wordt 'm gewoonweg niet. En vervolgens laat je het maar weer, ik begrijp je!

En wat betekent dat?

Kortom, wil een IT-specialist documenteren dan volstaan de klassieke officepakketten en overige systemen, waar andere wellicht prima mee uit de voeten kunnen, niet.

Laten we eens een pakket van eisen opstellen waar een documentatiesysteem voor een IT-specialist aan moet voldoen:

• Het moet zeer laagdrempelig zijn, zo laagdrempelig dat het net iets meer moeite kost dan totaal geen moeite. Denk hierbij aan het selecteren van een aantal commando's in een console, dan moet knip-plak-save voldoende zijn.
• De tool moet het overal doen, op ieder platform en device. Hierbij kun je denken aan een web-interface, je hebt eigenlijk wel altijd en overal een browser tot je beschikking.
• Het moet vrij zijn van auto-correct functies, want wat je met knip-plak overzet is correct omdat het in de console werkte. En dan dus vrij zijn van auto-correct, uitschakelbaar is niet genoeg. Dan komen we een keer van een ander device en staat het weer aan. Of na een update. Dan haakt de IT'er af!
• Ondersteuning bij het formatteren van een pagina kan wel weer wenselijk en/of handig zijn. Maar alleen als ik het wil! Dus bijvoorbeeld een bullet-list maken van lijstjes met sterretjes of mintekens. Maar het liefst in de platte tekst editor, een GUI-functie hiervoor mag maar is een extra!
• Een hele goede zoekfunctie zodat ook ongestructureerde krabbels ten alle tijde terug gevonden kunnen worden. Ik heb vaak genoeg tools gezien die "zoeken" wel geïmplementeerd hadden, maar "vinden" helaas niet. De te kiezen oplossing moet ook onze krabbels gewoon kunnen vinden.
• Het liefst met een opslagsysteem dat we het ook kunnen inzien op "de UNIX way of life", dus met command-line commando's. Handig als de webserver niet meer wil starten tijdens een grote storing of zo. Wij moeten dan troubleshooten en hebben de documentatie nodig. We moeten er altijd bij kunnen!
• Bij voorkeur voorzien van een automatisch versiebeheer systeem zodat wij ook hier niet zelf over hoeven na te denken. Want we zijn nog steeds lui tenslotte 😉.
  
  

Geschikte systemen voor techneuten

De laatste tijd zijn technieken zoals "Infrastructure-As-Code" (IAC) enorm in opkomst.

Het idee achter dergelijke technieken is dat de code tegelijkertijd zowel configuratie als documentatie is.

Soms wordt er nog een klein stukje additionele documentatie toegevoegd welke dan ook in de (code)repository zitten, vaak in de vorm van een bestand in een bepaalde syntax welke is afgeleid van die van diverse wiki-software (kortweg wiki's).

En dat brengt mij weer terug op klassieke documentatie, want wiki's vormen vaak een uitstekende oplossing voor een IT-specialist: de meeste wiki's vullen het grootse gedeelte van bovenstaand eisen- en wensenlijstje in. Je hebt deze wiki's in alle soorten en maten, waarbij MediaWiki en Dokuwiki de bekendste zijn. MediaWiki blinkt uit in, de naam zegt het al, Media. Het is ook niet voor niets de software achter grote projecten zoals WikiPedia die veel doen met diverse soorten media. De Dokuwiki is zoals gezegd ook een hele bekende, maar die heeft als voornaamste focus het schrijven van documentatie. Het voldoet aan alle bovenstaande eisen. Bovendien is het voorzien van een rechten-systeem noodzakelijk zodat niet iedereen alle documentatie kan en mag inzien.

Samen sparren

Kortom: kijk nog eens een keertje naar de documentatie. Documentatie is belangrijk, gewenst, noodzakelijk. Maar zoals zo vaak is goed gereedschap het halve werk.

Ik hoop in deze blog wat meer licht geworpen te hebben hierop. Wellicht spreek ik je nog een keer over dit soms lastige onderwerp, mijn collega’s en ik helpen je hier graag bij!