Tehokkaiden käyttöesimerkkien kirjoittaminen
Opettele laatimaan toimivia, suoraan kopioitavia esimerkkejä sekä tee/älä tee -pareja, jotka tekevät design-järjestelmän dokumentaatiosta aidosti hyödyllistä kehittäjille ja suunnittelijoille.
Tehokkaiden käyttöesimerkkien kirjoittaminen on ilmainen Suunnittelujärjestelmät ja komponenttikirjastot-oppitunti CoddyKitissä. Tämä on oppitunti 4/4. Voit lukea koko oppitunnin alta ilmaiseksi ja harjoitella sen jälkeen käytännössä selaimessa sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla. Oppitunti kuuluu Suunnittelujärjestelmät ja komponenttikirjastot-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Suunnittelujärjestelmät ja komponenttikirjastot-kurssilla on yhteensä 4 oppituntia.
Esimerkit ovat paras dokumentaatio
Kehittäjät oppivat komponentin nopeimmin näkemällä sen käytössä. Hyvä käyttöesimerkki korvaa usein kokonaisia tekstikappaleita.
Tässä oppitunnissa keskitytään kirjoittamaan esimerkkejä, jotka opettavat eivätkä vain koristele dokumentaatiota.
Esitelkää yleisin käyttötapaus ensin
Aloittakaa esimerkistä, jota 90 % käyttäjistä tarvitsee – yksinkertaisimmasta ja tyypillisimmästä käyttötavasta.
Poikkeustapaukset ja edistyneet määritykset tulevat myöhemmin. Jos ensimmäinen esimerkki on monimutkainen, säikytätte ihmiset pois ennen kuin he ehtivät aloittaa.
Suoraan kopioitavat koodinpätkät
Esimerkkien pitäisi olla suoraan kopioitavissa ja ajettavissa, ei pseudokoodia, jossa on ...-paikkamerkkejä.
Kehittäjän pitäisi voida liittää koodinpätkänsä projektiin ja nähdä sen toimivan. Alla oleva esimerkki on täydellinen ja itsenäinen.
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.'));Elävät ja muokattavat esimerkit
Paras ratkaisu on elävä leikkikenttä, jossa käyttäjät muokkaavat propseja ja näkevät tulokset heti.
Storybookin controls-työkalujen kaltaiset työkalut antavat ihmisten kokeilla asioita poistumatta dokumentaatiosta. Vuorovaikutteisuus muuttaa lukemisen ymmärtämiseksi.
Tee ja älä tee -parit
Näyttäkää oikea ja virheellinen käyttötapa vierekkäin. Rinnakkainen tee / älä tee opettaa harkintaa eikä vain syntaksia.
- Tee: käytä yhtä ensisijaista painiketta näkymää kohden.
- Älä tee: aseta kolmea ensisijaista painiketta kilpailemaan huomiosta.
Nämä parit ehkäisevät yleisimpiä väärinkäyttötapoja.
Selittäkää miksi
Esimerkki näyttää miten; lyhyt huomautus selittää miksi. Yhdistäkää jokaiseen ohjeeseen sen perustelu.
Kun ihmiset ymmärtävät perustelun, he osaavat soveltaa sääntöä oikein myös tilanteissa, joita ette ole dokumentoineet.
Kattakaa todelliset tilanteet
Käyttäkää realistista sisältöä, ei Lorem ipsum-tekstiä tai foo-arvoja. Näyttäkää oikea lomake, oikea virheilmoitus ja oikea kortti, jossa on todellinen tuote.
Realistiset esimerkit paljastavat välitykseen, ylivuotoon ja rivittymiseen liittyvät ongelmat, jotka paikkamerkkiteksti piilottaa.
Esitelkää tilat
Komponenteilla on tiloja: oletus, hover, käytöstä poistettu, lataus ja virhe. Dokumentoikaa jokainen esimerkin avulla.
Jos näytätte vain oletustilan, käyttäjät eivät tiedä käytöstä poistetun tilan olevan olemassa tai miten latausilmaisin otetaan käyttöön.
Pitää esimerkit ajan tasalla
Vanhentuneet esimerkit ovat pahempia kuin esimerkkien puuttuminen – ne opettavat vanhentuneita toimintatapoja. Kytkekää esimerkit suoraan toimivaan komponenttiin, jotta ne rikkoutuvat rajapinnan muuttuessa.
Lähdekoodista automaattisesti luodut esimerkit pysyvät määritelmän mukaan ajan tasalla.
Saavutettavuus esimerkeissä
Näyttäkää hyvää esimerkkiä. Jos esimerkeistänne puuttuvat nimilaput tai niiden kontrasti on heikko, ihmiset kopioivat nämä virheet.
Jokaisen esimerkin pitäisi olla saavutettava versio, jotta kopiointi ja liittäminen levittävät hyviä käytäntöjä bugien sijaan.
Esimerkit rakentavat luottamusta
Kun esimerkit ovat täydellisiä, ajan tasalla ja realistisia, kehittäjät luottavat dokumentaatioon eivätkä enää lähetä teille jatkuvasti kysymyksiä.
Huolella laaditut esimerkit ovat tehokkainta dokumentaatiota, jota voitte kirjoittaa.
Pikakoe
Testatkaa dokumentointivaistoanne.
Kertaus
Opitte kirjoittamaan opettavia käyttöesimerkkejä:
- Esitelkää yleisin käyttötapaus ensin ja poikkeustapaukset sen jälkeen.
- Tehkää koodinpätkistä suoraan kopioitavia ja mieluiten eläviä ja muokattavia.
- Käyttäkää tee/älä tee -pareja ja selittäkää miksi.
- Käyttäkää realistista sisältöä, kattakaa eri tilat ja pitäkää esimerkit synkronoituina.
Hyvät esimerkit ovat minkä tahansa design system -dokumentaation käytetyin osa.
Opi Suunnittelujärjestelmät ja komponenttikirjastot tekoälytuutorin avulla — ilmaiseksi
Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.
- Kurssit
- 12
- Oppitunnit
- 48
Usein kysytyt kysymykset
Onko oppitunti ”Tehokkaiden käyttöesimerkkien kirjoittaminen” ilmainen?
Kyllä – oppitunnin ”Tehokkaiden käyttöesimerkkien kirjoittaminen” koko tekstin voi lukea täällä verkossa ilmaiseksi. Jos haluat harjoitella interaktiivisesti sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla sekä avata koko Suunnittelujärjestelmät ja komponenttikirjastot-kurssin, päivitä CoddyKit PROhon. Suunnittelujärjestelmät ja komponenttikirjastot-kurssilla on yhteensä 4 oppituntia.
Mitä opin oppitunnilla ”Tehokkaiden käyttöesimerkkien kirjoittaminen”?
Opettele laatimaan toimivia, suoraan kopioitavia esimerkkejä sekä tee/älä tee -pareja, jotka tekevät design-järjestelmän dokumentaatiosta aidosti hyödyllistä kehittäjille ja suunnittelijoille. Harjoittelet Suunnittelujärjestelmät ja komponenttikirjastot-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.
Tarvitsenko kokemusta aloittaakseni Suunnittelujärjestelmät ja komponenttikirjastot-opiskelun?
Aiempi kokemus ei ole tarpeen. CoddyKitin Suunnittelujärjestelmät ja komponenttikirjastot-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 4/4.
Kuinka kauan ”Tehokkaiden käyttöesimerkkien kirjoittaminen”-oppitunnin suorittaminen kestää?
Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.
Voinko kirjoittaa ja suorittaa koodia tällä Suunnittelujärjestelmät ja komponenttikirjastot-oppitunnilla?
Kyllä. Jokainen Suunnittelujärjestelmät ja komponenttikirjastot-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.
Kaikki tämän kurssin oppitunnit
- Miksi dokumentaatio on tärkeää
- Komponenttidokumentaation työkalut
- Osallistumis- ja käyttöohjeet
- Tehokkaiden käyttöesimerkkien kirjoittaminen