Effectieve gebruiksvoorbeelden schrijven

Ontwikkelaars leren een component het snelst door te zien hoe het wordt gebruikt. Een goed gebruiksvoorbeeld vervangt vaak alinea's uitleg.

In deze les ligt de nadruk op het schrijven van voorbeelden die iets aanleren, niet alleen je documentatie versieren.

Begin met het voorbeeld dat 90% van de gebruikers nodig heeft: het eenvoudigste en meest typische gebruik.

Randgevallen en geavanceerde configuraties komen later. Als het eerste voorbeeld complex is, jaag je mensen weg voordat ze beginnen.

Voorbeelden moeten uitvoerbaar zijn na kopiëren en plakken, geen pseudocode met ...-placeholders.

Een ontwikkelaar moet je fragment kunnen invoegen en meteen kunnen zien dat het werkt. Het onderstaande voorbeeld is compleet en zelfstandig.

De gouden standaard is een live playground waarin gebruikers props bewerken en direct resultaat zien.

Met hulpmiddelen zoals Storybook controls kunnen mensen experimenteren zonder de documentatie te verlaten. Interactiviteit verandert lezen in begrijpen.

Laat correct gebruik naast incorrect gebruik zien. Een vergelijking naast elkaar van Wel doen en Niet doen leert inschatten wat juist is, niet alleen syntaxis.

• Wel doen: gebruik één primaire knop per weergave.
• Niet doen: plaats drie primaire knoppen naast elkaar die om aandacht strijden.

Deze combinaties voorkomen de meest voorkomende vormen van verkeerd gebruik.

Een voorbeeld laat zien hoe; een korte toelichting legt uit waarom. Combineer elke richtlijn met de reden erachter.

Als mensen de achterliggende reden begrijpen, passen ze de regel ook correct toe in situaties die je nooit hebt gedocumenteerd.

Gebruik realistische inhoud, geen Lorem ipsum en foo. Laat een echt formulier, een echte foutmelding en een echte kaart met een daadwerkelijk product zien.

Realistische voorbeelden brengen problemen met tussenruimte, overlopen en afbreken aan het licht die plaatshoudertekst verbergt.

Componenten hebben toestanden: standaard, hover, uitgeschakeld, laden en fout. Documenteer elke toestand met een voorbeeld.

Als je alleen de standaardtoestand laat zien, weten gebruikers niet dat er een stijl voor uitgeschakelde elementen bestaat of hoe ze de laadindicator activeren.

Verouderde voorbeelden zijn erger dan helemaal geen voorbeelden: ze leren verouderde patronen aan. Koppel voorbeelden aan het live component, zodat ze stukgaan wanneer de API verandert.

Automatisch gegenereerde voorbeelden uit de broncode blijven per definitie correct.

Laat goed gedrag zien. Als je voorbeelden labels overslaan of een slecht contrast gebruiken, nemen mensen die fouten over.

Elk voorbeeld moet de toegankelijke versie zijn, zodat kopiëren en plakken goede werkwijzen verspreidt in plaats van bugs.

Wanneer voorbeelden compleet, actueel en realistisch zijn, vertrouwen ontwikkelaars de documentatie en stoppen ze met jou vragen te sturen.

Goed uitgewerkte voorbeelden zijn de documentatie met de grootste impact die je kunt schrijven.

Je hebt geleerd gebruiksvoorbeelden te schrijven die iets aanleren:

• Laat eerst de meest voorkomende situatie zien en daarna de randgevallen.
• Maak fragmenten direct kopieerbaar en idealiter live en bewerkbaar.
• Gebruik combinaties van wel en niet doen en leg uit waarom.
• Gebruik realistische inhoud, behandel toestanden en houd voorbeelden gesynchroniseerd.

Goede voorbeelden zijn het meest gebruikte onderdeel van de documentatie van elk ontwerpsysteem.