De engineeringmuur, en wie erachter staat
Elk stuk documentatie in Storybook is een bestand in een repository. Dat is zijn superkracht - geversioneerd, gereviewd, samen met de code uitgerold - én zijn muur. De designer die weet waarom de destructieve knop rood is, kan dat niet opschrijven zonder engineer. De contentdesigner die een foute zin ziet, maakt een ticket in plaats van hem te herstellen. De muur staat in geen enkele featurelijst, maar bepaalt wie er bijdraagt: op den duur bevat Storybook-documentatie precies wat engineers bedachten op te schrijven, en niets anders. Dat is meestal uitstekende API-documentatie en vrijwel niets over wanneer, waarom, of óf je een component gebruikt.
Waar Storybook onverslaanbaar is, en we gaan niet doen alsof
Voor de code zelf kan niets ertegenop. Autodocs leest props, types en defaults uit de bron, dus die documentatie kán niet afdrijven - ze ís het component. De getoonde voorbeelden zijn het echte werk, interactief, in elke state. De geschiedenis is git, dus compleet en permanent, en dat verslaat onze 180 dagen zonder discussie. En het kost niets. Bestaat je hele publiek uit developers en is je systeem jong, dan is Storybook alleen een prima antwoord, en goedkoper dan wij ooit zullen zijn.
De meeste teams zouden beide moeten draaien, en dit is de verdeling
Storybook documenteert het component zoals gebouwd: API, states, gedrag - door engineers, voor engineers. Pentrical documenteert het systeem zoals ontworpen: richtlijnen, tokens, maten uit Figma, de redenering - door het hele team, voor het hele bedrijf. De overlap is kleiner dan hij lijkt, en de combinatie is gangbaar genoeg om hem de standaard te noemen: link van de richtlijnpagina naar de story, en van de story terug naar de richtlijn. Wat we zouden afraden is een van beide tools over de muur heen rekken - MDX-richtlijnen die niemand bijwerkt, of component-API's overgetypt in een CMS. Allebei zijn het manieren waarop documentatie sterft.
De kosten die nooit op een factuur belanden
Storybook is gratis zoals een puppy gratis is. De docs zijn code, dus elke verbetering concurreert met featurewerk in dezelfde sprint, gereviewd door dezelfde mensen. Teams die floreren met docs-as-code hebben besloten dat documentatie engineeringwerk is en er capaciteit voor vrijgemaakt. Teams die dat besluit niet hebben genomen, krijgen de andere uitkomst: een prachtige componentverkenner, zes MDX-pagina's uit 2024, en een design system dat in iemands hoofd woont. Herken je jouw Storybook hierin, dan is het probleem niet Storybook - maar dat de helft van de taak nooit zíjn taak was.
