Je kent het wel. Documentatie. Het ondergeschoven en zwaar onderschatte kindje van de automatisering. ‘De code is zelfverklarend’, ‘Read The Fine Manual’ en ‘Dat doen we later wel’. Veel gehoorde opmerkingen. Goed beheer gaat uiteraard om gedegen inhoudelijke kennis. Maar onderschat ook niet het vastleggen van afspraken, acties en het overzichtelijk in kaart brengen van de database omgeving. Lees: documentatie. Harry Splinter zet in deze blog een paar aandachtspunten uit de praktijk op een rij.
Duidelijke documentatie
Als we het over een standaard ‘Next, next, finish’-applicatie hebben, die verder geen afhankelijkheden of specifieke instellingen heeft, is de meegeleverde manual vaak voldoende. Daar zal niemand over discussiëren. Maar helaas is de praktijk toch vaak iets anders. Complexe (database-)omgevingen zijn er meer dan genoeg, dat hebben velen van ons aan den lijve ondervonden. Dan is het toch echt heel prettig om duidelijke documentatie te hebben.
Belang van duidelijke documentatie
Maar wat is dat dan, duidelijke documentatie? Zelf ga ik er vanuit dat documentatie voor een collega met domeinkennis leesbaar, begrijpelijk en uitvoerbaar moet zijn. Beschrijven hoe je een query moet samenstellen of hoe je een product moet installeren en configureren, dat hebben anderen al gedaan. Ook basiskennis is onzinnig om te omschrijven. Het zijn vooral de afwijkingen op de standaard die we willen vastleggen. Er zijn natuurlijk uitzonderingen zoals gebruikersnaam en wachtwoorden, die willen we niet in de, al dan niet openbare, documentatie. Een verwijzing naar waar deze te vinden zijn wel. Datzelfde geldt voor bronvermeldingen, een link is al voldoende.
Kennisdeling
Documentatie is ook zinnig als je het hebt over kennisdeling. Door kennis of ervaringen met je collega’s te delen, werk je mee aan de ontwikkeling van de afdeling of het bedrijf. Want ook voor buiten de afdeling kan kennisdeling nuttig zijn. Neem bijvoorbeeld een nieuwe feature in SQL-code. Zowel voor database-beheerders als ontwikkelaars is een beschreven toepassing plus voorbeeld van veel waarde.
Onder druk
We gaan er ook vanuit dat documentatie soms onder druk moet worden gebruikt. Wat logisch is, kan onder druk soms tot fouten leiden. Als voorbeeld verwijzen we terug een eerdere blog over databaserecovery. Als de documentatie niet klopt of onvoldoende gecontroleerd en getest is, loopt de stress onnodig op.
Aanvulling
Naast beschrijvingen zorg je ook voor eventuele voorbeelden, begeleidende afbeeldingen en architectuurplaten voor inzicht op een omgeving. Andere zaken waarmee je rekening moet houden zijn bijvoorbeeld vindbaarheid, doorzoekbaarheid, opbouw, taal (gebruik je Engels of schrijf je documentatie in een andere taal), standaarden (templates), verwijzingen, gevoeligheid van de gegevens (GDPR) en bereikbaarheid (centralisatie).
Review en testen!
En als de documentatie er is… vindt er een review plaats. Laat documentatie controleren. Wat voor de schrijver vaak logisch is, komt voor de ander misschien totaal niet over. Test ook beschreven procedures en code om er zeker van te zijn dat die correct zijn.
Tooling en functionaliteiten
De meeste van bovenstaande functionaliteiten zijn terug te vinden in tools, zoals online documentatie-applicaties, wiki’s of documenten (pdf, word, e-pub), elk met hun voor- en nadelen.
Confluence
Bij OptimaData werken we met één van de bekendste online documentatietools met diverse plug-ins: Confluence. Een duidelijke onderverdeling van klanten en hoofdstukken zorgen voor een overzichtelijk geheel, rekening houdend met het autorisatieschema. Dynamische architectuurplaten, zoals in onderstaande afbeelding, worden hierin opgenomen, net als voorbeeldcode en screenshots. Ook kun je hierin meetingverslagen en dagelijkse blogs gecentraliseerd terugvinden zodat iedereen, met de juiste autorisatie, bijdraagt aan elkaars kennis.
Meer weten?
Wil je ook (meer) structuur brengen in je database beheer? Wist je dat het in lijn brengen en professionaliseren van je documentatie ook een onderdeel is waar wij je bij kunnen ondersteunen? Neem gerust eens vrijblijvend contact op. We leren je graag kennen.
Andere interessante blogs:
De drie fases van effectief databasesupport
Blijf in controle over de rechten die je uitdeelt
Database Reliability Engineering