Regelmatig wordt door klanten de vraag gesteld hoe ze het beste kunnen documenteren. Aan de andere kant komt het ook voor dat klanten nooit gedocumenteerd hebben, omdat er geen tijd was, geen sjabloon. In dit blog ga ik in op vragen rondom documenteren en geef ik enkele voorbeelden aan de hand van Tableau. (Dit gaat niet over notities maken in Tableau, zie hiervoor dit blog).
Waarom documenteren?
Het is al een paar keer voorgekomen dat ik bij een klant kwam en er niet echt bijgehouden was wat er in een workbook gebeurt. De ene keer was alles terug te vinden in het hoofd van de bouwer, die gelukkig nog werkzaam was bij het bedrijf. De andere keer was de maker al vertrokken en had een summier document achter gelaten. In dat laatste geval bleek dat een belangrijk dashboards stuk ging per 1 januari. Uiteindelijk moest het hele dashboard uit elkaar getrokken worden om erachter te komen welke calculatie dit veroorzaakte.
Het is wel handig als een dashboard een handleiding heeft, al is het maar om na te gaan waarom er gekozen is voor bepaalde technische oplossingen of visuele standaarden.
Voor wie, door wie, hoe lang en waarmee?
Voordat ik inga op de manier waarop documentatie geschreven kan worden is het eerst goed om na te gaan wat het doel van de documentatie is. Maar ook hoeveel tijd u eraan kwijt wilt zijn. Een interne enquête onder TIL NL-consultants heeft de volgende ideeën en meningen opgeleverd.
Publiek
Voor wie schrijft u documentatie? Uit de antwoorden op de vragenlijst kwam naar voren dat de vaste gebruikers van de software (voor het gemak spreek ik vanaf nu van Tableau) de documentatie moeten kunnen gebruiken. Een aantal gaf als antwoord dat degene die een product (workflow, dashboard, stuk code) aanvraagt de documentatie zou moeten doen. Persoonlijk lijkt me dit wat lastig. Als elke afdeling bij BI aanvragen mag indienen betekent het niet dat ze in staat zijn de technische kant van een dashboard te snappen.
Auteur(s)
Zoals al hierboven besproken is het meest voor de hand liggende antwoord: de bouwer. Degene die het dashboard bouwt zou het beste bij kunnen houden wat hij bouwt en waarom.
Hoe lang?
Dit hangt uiteraard af van de omvang van het object en het detailniveau waarnaar gestreefd wordt (zie volgend blog). Zelf probeer ik het bij een pagina per worksheet te houden, maar hoe meer calculaties erbij komen kijken, hoe groter dat deel wordt.
Waarmee?
Dit verschilt per soort software, sommige programma’s bieden de mogelijkheid om aantekeningen en notities te tonen op het canvas (zoals Alteryx). Bij andere software heeft het mijn voorkeur om het in een tekstdocument te doen. Tableau biedt de mogelijkheid tot het maken van notities per worksheet en in calculaties. (Maar voor het overzicht vind ik persoonlijker één document waar alles bij elkaar staat fijner werken.)
Hoeveel tijd mag het kosten?
Een vuistregel waarmee collega’s kwamen was vier uur, idealiter worden aan het einde van de dag de losse notities toegevoegd aan de documentatie. Het laatste uur van de werkdag leent zich daar wellicht voor.
Wat is goede documentatie?
Nogmaals, dit hangt van het doel af, zijn de gebruikers allemaal gepokt en gemazeld in de software, dan kunnen credentials en een omschrijving volstaan. Wat meer nut heeft (naar mijn mening en die van enkele collega’s) is een document waarin keuzes vastgelegd worden en bijgehouden kan worden wat er wijzigt en waarom.
Het doel van documentatie is (volgens de enquête-resultaten) is om de Business Intelligence – afdeling wegwijs te maken in een workbook. Het is geen IKEA-handleiding voor elke medewerker zodat die zelf het dashboard na kan bouwen.
Als belangrijkste eigenschappen (en tegelijk het moeilijkste te combineren) werden ‘leesbaarheid’ en ‘accuraat en technisch’ door de ondervraagden genoemd.
Een tip van collega’s was om een sjabloon per software-product te maken, zodat het uiteindelijk een invuloefening wordt. Dit kan uiteindelijk tijd schelen en het bijhouden van documentatie minder vervelend maken.
Conclusie
Heel veel tekst, maar hoe ziet het er dan uit? In het volgende blog (zie deze link) heb ik een voorbeeld proberen te maken aan een (erg) standaard dashboard.