Skrive effektive brukseksempler
Lær å utforme levende, kopieringsklare eksempler og gjør/ikke gjør-par som gjør dokumentasjonen av designsystemet virkelig nyttig for utviklere og designere.
Skrive effektive brukseksempler er en gratis leksjon i Designsystemer og komponentbiblioteker på CoddyKit. Dette er leksjon 4 av 4. Du kan lese hele leksjonen gratis nedenfor – og deretter øve praktisk i nettleseren med en innebygd kodeeditor og en AI-veileder som er tilgjengelig døgnet rundt. Den er en del av læringsløpet i Designsystemer og komponentbiblioteker, og fremdriften din synkroniseres mellom nettet og CoddyKit-appen. Kurset i Designsystemer og komponentbiblioteker inneholder totalt 4 leksjoner.
Eksempler er den beste dokumentasjonen
Utviklere lærer seg en komponent raskest ved å se den i bruk. Et godt brukseksempel kan ofte erstatte avsnitt med tekst.
Denne leksjonen handler om å skrive eksempler som lærer bort noe, ikke bare pynter opp dokumentasjonen.
Vis det vanlige tilfellet først
Start med eksempelet 90 % av brukerne trenger – den enkleste og mest typiske bruken.
Spesialtilfeller og avanserte konfigurasjoner kommer senere. Hvis det første eksempelet er komplisert, skremmer De folk bort før de kommer i gang.
Kodebiter klare for kopiering
Eksempler bør kunne kjøres direkte etter kopiering og innliming, ikke være pseudokode med ...-plassholdere.
En utvikler bør kunne lime inn kodebiten og se at den fungerer. Eksempelet nedenfor er komplett og selvstendig.
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 ideelle er en interaktiv lekeplass der brukerne redigerer props og ser resultatene umiddelbart.
Verktøy som Storybook controls lar folk eksperimentere uten å forlate dokumentasjonen. Interaktivitet gjør lesing til forståelse.
Par med gjør og ikke gjør
Vis riktig bruk ved siden av feil bruk. Et side-ved-side-Gjør / Ikke gjør-eksempel lærer bort vurdering, ikke bare syntaks.
- Gjør: bruk én primærknapp per visning.
- Ikke gjør: plasser tre primærknapper sammen slik at de konkurrerer om oppmerksomheten.
Slike par forebygger de vanligste feilbrukene.
Forklar hvorfor
Et eksempel viser hvordan; en kort merknad forklarer hvorfor. Knytt hver retningslinje til begrunnelsen for den.
Når folk forstår begrunnelsen, bruker de regelen riktig i situasjoner De aldri har dokumentert.
Dekk reelle scenarier
Bruk realistisk innhold, ikke Lorem ipsum og foo. Vis et ekte skjema, en ekte feilmelding og et ekte kort med et faktisk produkt.
Realistiske eksempler avdekker problemer med avstand, innhold som flyter over, og linjebryting som plassholdertekst skjuler.
Vis tilstander
Komponenter har tilstander: standard, hover, deaktivert, lasting og feil. Dokumenter hver av dem med et eksempel.
Hvis De bare viser standardtilstanden, vet ikke brukerne at det finnes en deaktivert stil, eller hvordan de utløser lastingsindikatoren.
Hold eksemplene ved like
Utdaterte eksempler er verre enn ingen eksempler – de lærer bort utdaterte mønstre. Knytt eksemplene til den aktive komponenten, slik at de slutter å fungere når API-et endres.
Auto-genererte eksempler fra kildekoden holder seg korrekte per definisjon.
Tilgjengelighet i eksempler
Vær et godt forbilde. Hvis eksemplene Deres mangler etiketter eller bruker dårlig kontrast, kopierer folk disse feilene.
Alle eksempler bør være den tilgjengelige versjonen, slik at kopiering og innliming sprer god praksis i stedet for feil.
Eksempler skaper tillit
Når eksemplene er komplette, oppdaterte og realistiske, stoler utviklerne på dokumentasjonen og slutter å sende Dem spørsmål.
Gjennomarbeidede eksempler er den mest effektive dokumentasjonen De kan skrive.
Rask sjekk
Test instinktene Deres for dokumentasjon.
Oppsummering
De har lært å skrive brukseksempler som lærer bort noe:
- Vis det vanlige tilfellet først, og deretter spesialtilfeller.
- Gjør kodebiter klare for kopiering, og helst interaktive og redigerbare.
- Bruk par med gjør og ikke gjør, og forklar hvorfor.
- Bruk realistisk innhold, dekk ulike tilstander, og hold eksemplene synkronisert.
Gode eksempler er den mest brukte delen av dokumentasjonen til ethvert designsystem.
Lær deg Designsystemer og komponentbiblioteker med en AI-veileder – gratis
Skriv og kjør ekte kode i nettleseren, få umiddelbar hjelp fra en AI-veileder som er tilgjengelig døgnet rundt, og fortsett der du slapp – på nettet eller i appen.
- Kurs
- 12
- Leksjoner
- 48
Ofte stilte spørsmål
Er leksjonen «Skrive effektive brukseksempler» gratis?
Ja – hele teksten i «Skrive effektive brukseksempler» er gratis å lese her på nettet. For å øve interaktivt med en innebygd kodeeditor og en AI-veileder som er tilgjengelig døgnet rundt, og for å låse opp resten av Designsystemer og komponentbiblioteker-kurset, kan du oppgradere til CoddyKit PRO. Kurset i Designsystemer og komponentbiblioteker inneholder totalt 4 leksjoner.
Hva lærer jeg i «Skrive effektive brukseksempler»?
Lær å utforme levende, kopieringsklare eksempler og gjør/ikke gjør-par som gjør dokumentasjonen av designsystemet virkelig nyttig for utviklere og designere. Du øver på Designsystemer og komponentbiblioteker med praktisk kode som du kjører direkte i nettleseren, mens en AI-veileder som er tilgjengelig døgnet rundt, svarer på spørsmålene dine mens du jobber deg gjennom leksjonen.
Trenger jeg erfaring for å begynne med Designsystemer og komponentbiblioteker?
Ingen tidligere erfaring er nødvendig. Designsystemer og komponentbiblioteker på CoddyKit er lagt opp for både nybegynnere og viderekomne, så De kan begynne her eller helt fra start og lære i Deres eget tempo. Dette er leksjon 4 av 4.
Hvor lang tid tar leksjonen «Skrive effektive brukseksempler»?
De fleste CoddyKit-leksjoner tar omtrent 5–10 minutter. Hver leksjon er kort og interaktiv, slik at De gjør jevne fremskritt og kan fortsette akkurat der De slapp – både på nettet og i appen.
Kan jeg skrive og kjøre kode i denne Designsystemer og komponentbiblioteker-leksjonen?
Ja. Alle Designsystemer og komponentbiblioteker-leksjoner har en innebygd kodeeditor, slik at De kan skrive og kjøre ekte kode direkte i nettleseren og få umiddelbar tilbakemelding fra AI – uten lokal konfigurering.
Alle leksjonene i dette kurset
- Hvorfor dokumentasjon er viktig
- Verktøy for komponentdokumentasjon
- Retningslinjer for bidrag og bruk
- Skrive effektive brukseksempler