Werkplaats / 02
Mijn website heeft inmiddels een eigen handboek
Hoe ik met Storybook ontwerp, techniek en documentatie op één plek samenbreng.
Een eigen project
Het begon met een duidelijk plan.
Ik weet niet precies hoe ik het iedere keer voor elkaar krijg, maar mijn eigen projecten worden bijna altijd uitgebreider dan ik vooraf had bedacht.
Ik begin met een duidelijk plan, maar wanneer ik aan iets voor mezelf werk, geef ik mezelf ook de ruimte om tijdens het ontwikkelen nieuwe mogelijkheden te onderzoeken. Onderweg kom ik dan vaak op ideeën die ik vooraf nog niet had voorzien.
Met Storybook is dat eigenlijk precies zo gegaan.
Terwijl ik daarmee bezig was, begon ik steeds meer mogelijkheden te zien. Het werd eigenlijk alleen maar leuker naarmate ik verder kwam en daardoor ontstond het idee om niet alleen mijn componenten te documenteren, maar ook mijn ontwerpkeuzes, de structuur van mijn website en de techniek erachter inzichtelijk te maken.
Zo heb ik de oorspronkelijke opzet stap voor stap uitgebreid. Inmiddels begint Storybook behoorlijk op een compleet handboek voor mijn website te lijken.
Steeds een stukje verder
Het ene idee brengt het volgende mee.
Die uitbreiding begon eigenlijk al bij de onderdelen die ik vanaf het begin wilde documenteren.
De kleuren stonden al in mijn oorspronkelijke overzicht, maar ik wilde er gaandeweg meer over kunnen zien. Inmiddels kan ik terugvinden waar ze binnen de website worden toegepast en hoe vaak bepaalde kleurwaarden in de code voorkomen.
Daarna ben ik ook de verschillende pagina's, de navigatiestructuur en de metadata uitgebreider in kaart gaan brengen. Zo kan ik controleren of SEO-titels, metabeschrijvingen en andere belangrijke gegevens op iedere pagina aanwezig zijn.
Wat ik daar zelf zo leuk aan vind, is dat ik tijdens het uitwerken steeds weer mogelijkheden ontdek. Door alles zo in kaart te brengen, zie ik ook waar ik mijn website nog kan verbeteren.
Ook achter de schermen overzicht houden
De techniek verdient ook een eigen plek.
Na de visuele onderdelen en de paginastructuur wilde ik ook meer inzicht krijgen in de techniek achter mijn website. Vooral de externe pakketten die ik tijdens het ontwikkelen gebruik, vond ik interessant om eens goed in kaart te brengen.
Tijdens het ontwikkelen installeer je regelmatig nieuwe bibliotheken. De ene gebruik je voor animaties, de andere voor het opsporen van technische fouten, het analyseren van bezoekersgedrag of het versturen van e-mails via een contactformulier.
Na verloop van tijd wordt het best lastig om precies te onthouden waarvoor ieder pakket is toegevoegd en waar het binnen de website wordt gebruikt. Daarom heb ik ook een npm-bibliotheek aan Storybook toegevoegd.
Daarin kan ik terugvinden welke pakketten zijn geïnstalleerd, waarvoor ze dienen, waar ik ze toepas en of er updates beschikbaar zijn. Ook de bijbehorende documentatie en configuratie zijn vanuit het overzicht bereikbaar.
Zo kan ik bij een aanpassing of update sneller achterhalen welke onderdelen ermee te maken hebben.
Een handboek dat met de website meegroeit
Steeds meer kennis op één plek.
Gaandeweg merkte ik dat ik naast informatie over componenten en technische pakketten ook steeds meer kennis verzamelde over mijn ontwikkelomgeving en werkwijze. Dingen die tijdens het bouwen vanzelfsprekend lijken, maar die je een paar maanden later misschien niet meer zo goed in je hoofd hebt.
Daarom ben ik binnen Storybook begonnen met een apart ontwikkelhandboek. Daarin leg ik onder meer vast hoe ik met Git en GitHub werk, hoe deployments verlopen en welke integraties mijn website gebruikt. Ook testen, onderhoud en het oplossen van veelvoorkomende problemen hebben er een plek gekregen, inclusief praktische checklists.
Het uitwerken daarvan heeft behoorlijk wat tijd gekost. Tegelijkertijd vind ik het ontzettend leuk om zoiets steeds verder te ontwikkelen.
Tijdens het documenteren kijk ik bovendien opnieuw naar mijn eigen keuzes. Soms ontdek ik dat iets eenvoudiger kan, dat er informatie ontbreekt of dat ik een onderdeel beter kan organiseren.
Waarom ik hier zoveel aandacht aan besteed
Overzicht helpt me verder ontwikkelen.
Naarmate mijn website groeit, komen er meer onderdelen, technische afhankelijkheden en keuzes bij. Tijdens het ontwikkelen weet ik doorgaans hoe alles in elkaar zit, maar over een paar maanden heb ik niet iedere beslissing of aanpassing nog paraat.
Door die informatie op één plek vast te leggen, kan ik sneller terugvinden hoe iets werkt. Ik krijg ook beter zicht op de samenhang tussen onderdelen en op de gevolgen die een wijziging ergens anders in de website kan hebben.
Ook voor andere ontwikkelaars
De website moet ook voor anderen begrijpelijk blijven.
Ik wil ook dat andere ontwikkelaars mijn website kunnen begrijpen, onderhouden en verder ontwikkelen. Mocht iemand anders er in de toekomst aan werken, dan moet diegene kunnen terugvinden hoe alles is opgebouwd en welke keuzes ik heb gemaakt.
Met duidelijke documentatie is er een vertrekpunt. Een andere ontwikkelaar hoeft dan niet eerst de hele code uit te pluizen om te begrijpen hoe onderdelen samenwerken en waar rekening mee gehouden moet worden.
Wat dit voor klanten betekent
Een goede basis blijft waardevol.
Diezelfde aandacht voor onderhoud en overdraagbaarheid neem ik mee in mijn werk voor klanten. Bij een website of digitaal systeem is het belangrijk dat technische keuzes en afspraken ook na de oplevering terug te vinden zijn.
Voor klanten kan dat zorgen voor meer continuïteit en minder afhankelijkheid van één ontwikkelaar. Wanneer er later iets aangepast of uitgebreid moet worden, of iemand anders het onderhoud overneemt, is er een duidelijke basis om op verder te bouwen.
Hoe uitgebreid de documentatie moet zijn, hangt natuurlijk af van het project. De gedachte erachter blijft hetzelfde: een systeem moet ook op langere termijn begrijpelijk en onderhoudbaar zijn.
Ik heb er uiteindelijk veel meer tijd in gestoken dan vooraf gedacht. Maar iedere uitbreiding maakt het makkelijker om mijn website te begrijpen, te onderhouden en verder te ontwikkelen. En juist daarom is dat handboek iets waar ik nog vaak op terug zal vallen.