Het hebben van documenten ter ondersteuning van het voortbrengen van een softwareproduct is niet ongewoon. Je moet immers een handleiding uitleveren, evenals releasenotes en wellicht een licentieovereenkomst. We krijgen wel vaker de vraag van klanten wat ze met documenten moeten. Waar moeten die opgeslagen worden? Denk bijvoorbeeld aan (architectuur)richtlijnen voor ontwikkelaars, runbooks voor de installatie van de applicatie, lijsten met te installeren software voor buildservers, voor ontwikkelmachines et cetera. De wedervraag is dan: waarom schrijf je deze documentatie? Het kost veel tijd en het opvolgen van de beschreven constructies gaat ook wel eens mis, door bijvoorbeeld een menselijke fout.
DevOps practices
Als we kijken naar DevOps practices, proberen we zoveel mogelijk kennis vast te leggen in systemen en niet in hoofden van mensen of in documenten. Het pad van idee tot “in productie” voor klanten dient zo kort en eenvoudig mogelijk te zijn. Wanneer het kort en eenvoudig is, kan er meer moeite gestoken worden in leveren van waarde voor de klant en is de kans op hoge kwaliteit significant groter. Wanneer dit pad geblokkeerd/vertraagd wordt door zaken die ook geautomatiseerd afgehandeld kunnen worden, dan moet je je afvragen waar je je energie in steekt.
Scripts boven instructies en lijsten
Een runbook is een goed voorbeeld. Waarom wordt een runbook samengesteld? Dit is een instructie waarin bijvoorbeeld het installatieproces van een applicatie beschreven wordt. De vraag is uiteraard, waarom dit in een document beschreven wordt, terwijl dezelfde acties ook via een script geautomatiseerd uitgevoerd kunnen worden. Het voordeel is duidelijk; het script documenteert het installatieproces en het is een stuk eenvoudiger uit te voeren dan een runbook.
Een ander voorbeeld is de lijst met te installeren software voor een buildserver. Waarom is dit een lijst? Worden die installaties echt elke keer opnieuw met de hand uitgevoerd? Via bijvoorbeeld https://chocolatey.org in combinatie met PowerShell is dit zeer eenvoudig te automatiseren. Door het te automatiseren kunnen we veel sneller zo’n server beschikbaar stellen als er behoefte aan is. Ook de kennis ligt weer vast in het script. Het script kunnen we dan in Version Control (bijvoorbeeld Git) vastleggen, waardoor we meteen versiehistorie hebben.
Kortom, wanneer je documentatie schrijft, vraag jezelf af of je hetzelfde doel niet kunt bereiken door het te automatiseren! Automatiseren is onze expertise toch?
Fokko Veegens, DevOps Consultant
