Skriv effektive brugseksempler
Lær at udforme interaktive eksempler, der er klar til kopiering, samt do/don't-par, som gør dokumentationen til designsystemet reelt nyttig for udviklere og designere.
Skriv effektive brugseksempler er en gratis Designsystemer og komponentbiblioteker-lektion på CoddyKit. Dette er lektion 4 af 4. Du kan læse hele lektionen gratis nedenfor — og derefter øve dig praktisk i browseren med en indbygget kodeeditor og en AI-vejleder, der er tilgængelig døgnet rundt. Den er en del af læringsforløbet i Designsystemer og komponentbiblioteker, og dine fremskridt synkroniseres på tværs af nettet og CoddyKit-appen. Designsystemer og komponentbiblioteker-kurset indeholder 4 lektioner i alt.
Eksempler er den bedste dokumentation
Udviklere lærer en komponent hurtigst ved at se den i brug. Et godt brugseksempel erstatter ofte afsnit med tekst.
Denne lektion handler om at skrive eksempler, der underviser, ikke bare pynter i din dokumentation.
Vis standardtilfældet først
Start med det eksempel, som 90 % af brugerne har brug for – den enkleste og mest typiske anvendelse.
Edge cases og avancerede konfigurationer kommer senere. Hvis det første eksempel er komplekst, skræmmer du folk væk, før de kommer i gang.
Klar-til-kopiering-kodestykker
Eksempler skal kunne køres efter copy-paste, ikke være pseudokode med pladsholdere som ....
En udvikler skal kunne indsætte dit kodestykke og se det fungere. Eksemplet nedenfor er komplet og selvstændigt.
function Alert(type, message) {
return '<div class="alert alert-' + type + '">' + message + '</div>';
}
console.log(Alert('success', 'Saved successfully!'));
console.log(Alert('error', 'Something went wrong.'));Interaktive, redigerbare eksempler
Det bedste er en interaktiv legeplads, hvor brugerne redigerer props og ser resultaterne med det samme.
Værktøjer som Storybook controls lader folk eksperimentere uden at forlade dokumentationen. Interaktivitet gør læsning til forståelse.
Par med gør og gør ikke
Vis korrekt brug ved siden af forkert brug. Et side-om-side-par med Gør / Gør ikke lærer dømmekraft, ikke bare syntaks.
- Gør: Brug én primær knap pr. visning.
- Gør ikke: Placér tre primære knapper oven på hinanden, så de konkurrerer om opmærksomheden.
Disse par forebygger de mest almindelige fejl.
Forklar hvorfor
Et eksempel viser hvordan; en kort note forklarer hvorfor. Knyt en begrundelse til hver retningslinje.
Når folk forstår rationalet, anvender de reglen korrekt i situationer, du aldrig har dokumenteret.
Dæk virkelige scenarier
Brug realistisk indhold, ikke Lorem ipsum og foo. Vis en virkelig formular, en virkelig fejlmeddelelse og et virkeligt kort med et rigtigt produkt.
Realistiske eksempler afslører problemer med afstande, overløb og linjeombrydning, som pladsholdertekst skjuler.
Vis tilstande
Komponenter har tilstande: standard, hover, deaktiveret, indlæser og fejl. Dokumentér hver af dem med et eksempel.
Hvis du kun viser standardtilstanden, ved brugerne ikke, at den deaktiverede stil findes, eller hvordan indlæsningsindikatoren udløses.
Vedligehold eksemplerne
Forældede eksempler er værre end ingen eksempler – de lærer folk forældede mønstre. Knyt eksemplerne til den aktive komponent, så de går i stykker, når API'et ændres.
Auto-genererede eksempler fra kildekoden er pr. definition korrekte.
Tilgængelighed i eksempler
Vis god praksis. Hvis dine eksempler mangler labels eller bruger dårlig kontrast, kopierer folk disse fejl.
Alle eksempler bør være den tilgængelige version, så copy-paste spreder god praksis i stedet for fejl.
Eksempler skaber tillid
Når eksempler er komplette, aktuelle og realistiske, stoler udviklere på dokumentationen og holder op med at sende dig spørgsmål.
Gennemtænkte eksempler er den dokumentation, du kan få mest ud af at skrive.
Hurtigt tjek
Test din fornemmelse for god dokumentation.
Opsummering
Du har lært at skrive brugseksempler, der underviser:
- Vis standardtilfældet først og derefter edge cases.
- Gør kodestykker klar til kopiering og helst interaktive og redigerbare.
- Brug par med gør og gør ikke, og forklar hvorfor.
- Brug realistisk indhold, dæk tilstande, og hold eksemplerne synkroniserede.
Gode eksempler er den mest anvendte del af dokumentationen til ethvert designsystem.
Lær Designsystemer og komponentbiblioteker med en AI-underviser — gratis
Skriv og kør rigtig kode i din browser, få øjeblikkelig hjælp fra en AI-underviser døgnet rundt, og fortsæt, hvor du slap, på web eller i appen.
- Kurser
- 12
- Lektioner
- 48
Ofte stillede spørgsmål
Er lektionen “Skriv effektive brugseksempler” gratis?
Ja — hele teksten til “Skriv effektive brugseksempler” kan læses gratis her på nettet. Hvis du vil øve dig interaktivt med en indbygget kodeeditor og en AI-vejleder døgnet rundt og få adgang til resten af Designsystemer og komponentbiblioteker-kurset, skal du opgradere til CoddyKit PRO. Designsystemer og komponentbiblioteker-kurset indeholder 4 lektioner i alt.
Hvad lærer jeg i “Skriv effektive brugseksempler”?
Lær at udforme interaktive eksempler, der er klar til kopiering, samt do/don't-par, som gør dokumentationen til designsystemet reelt nyttig for udviklere og designere. Du øver dig i Designsystemer og komponentbiblioteker med praktisk kode, som du kører direkte i browseren, og en AI-vejleder døgnet rundt besvarer dine spørgsmål, mens du arbejder dig gennem lektionen.
Skal jeg have erfaring for at begynde på Designsystemer og komponentbiblioteker?
Der kræves ingen tidligere erfaring. Designsystemer og komponentbiblioteker på CoddyKit er tilrettelagt for både begyndere og øvede, så du kan starte her eller fra begyndelsen og lære i dit eget tempo. Dette er lektion 4 af 4.
Hvor lang tid tager lektionen “Skriv effektive brugseksempler”?
De fleste CoddyKit-lektioner tager cirka 5–10 minutter. Hver lektion er kort og interaktiv, så du gør løbende fremskridt og kan fortsætte, hvor du slap – på både web og app.
Kan jeg skrive og køre kode i denne Designsystemer og komponentbiblioteker-lektion?
Ja. Alle Designsystemer og komponentbiblioteker-lektioner har en indbygget kodeeditor, så du kan skrive og køre rigtig kode direkte i din browser og få øjeblikkelig feedback fra AI – uden lokal opsætning.
Alle lektioner i dette kursus
- Hvorfor dokumentation er vigtig
- Værktøjer til komponentdokumentation
- Retningslinjer for bidrag og brug
- Skriv effektive brugseksempler