Hva bør være minimumet til komponentdokumentasjon?

[wkillerud]

Vi er ikke helt konsekvente i hva vi har med av dokumentasjon på de ulike komponentsidene. Lurer på om det er noen innspill til hva som bør være minimumet av dokumentasjon inne på https://jokul.fremtind.no/komponenter/accordion og venner? Hva leter du etter?

[wkillerud]

"Må ha" for komponenteksempler i portalen:

• Ingress med kort beskrivelse av komponenten
• Første eksempel synlig uten å scrolle
• Relevante eksempler på riktig og feil bruk
• Live kodeeksempel (oppdateres med valgte egenskaper)
• React-props for komponentene i bunnen

"Vil ha" for komponenteksempler i portalen:

• Kontrollspørsmål for bruk
• Lenker til relevante eller alternative komponenter der det er naturlig
• Eksempler på bruk ute i teamene

[onordbo]

Hvor burde disse minstekravene leve, for at vi skal gjøre det enklest mulig for alle å forholde seg til dem?

[wkillerud]

Forum 16.11

Viste tre eksempler:

• https://jokul.fremtind.no/komponenter/tag
• https://jokul.fremtind.no/komponenter/table
• https://jokul.fremtind.no/komponenter/hamburger

Av de tre ble Tags sett på som "best". Særlig det med eksempler på riktig og feil bruk, med eksempler i gjenkjennelig kontekst. Det at det er noen kontrollspørsmål der for om dette er riktig komponent ble også fremhevet. "Låser ikke, men får en til å tenke litt ekstra". Likte også lenker til relaterte komponenter (MessageBox).

Et forslag som ble nevnt var å få inn eksempler fra designerne i teamene på hvordan komponenten blir brukt. Skjermbilder, eller som basis for Dos and Donts. (Noe for show and tell på forum?)

Viktig at hver komponent har en ingress og et visuelt eksempel "above the fold".

I overkant teknisk dokumentasjon til tider, for eksempel for Table som går rett på komponenter og HTML. Viktig dokumentasjon, men bare for et utvalg av brukerne. Skulle vi ha delt inn i to seksjoner? Generell dokumentasjon og veldig teknisk? Material UI ble fremhevet som et godt eksempel, med seksjoner for Design og Implementation.

[wkillerud]

Laget et prosjekt med oversikt over alle komponentene og hvilke mangler de har sett opp mot #2500 (comment)

✨📖 https://github.com/fremtind/jokul/projects/9 📖✨

Help wanted 👋

Det er 28 sider dokumentasjon som trenger varierende grad av TLC. Velg deg et kort fra prosjektet, trykk på ... og velg Convert to issue, så assign deg selv for å vise at du er på saken. Åpne en pull request knyttet til issuet (mer om hvordan finner du her), så oppdaterer prosjekt-boardet seg automatisk i bakgrunnen helt frem til Done.

[onordbo]

Vi har ikke snakket veldig mye om hva vi opplever som tydelige rammebetingelser for hva man skal ha laget av design, kode og dokumentasjon for å møte et minstekrav til å lansere noe i Jøkul. Jeg synes det er bra at vi tar opp dette, dog synes jeg vi skal ekspandere det til å dekke hele bredden av et bidrag eller en komponent i Jøkul (hvertfall for helt nye bidrag). Jeg har et par forslag til hva som burde inngå av minstekrav:

• Bidraget burde være dokumentert i portalen med formål, et (interaktivt) 
eksempel (og live kode?), prinsipper for bruk, og relevante tilgjengelige funksjoner/APIer
• Designet burde være dokumentert i en egen branch i Figma-biblioteket 
(med varianter ved behov), klart for å merges inn, og være sjekket av med minst
 en annen designer (som kjenner biblioteket godt?) eller kjerneteamet.
• Koden burde ha blitt gjennomgått av andre utviklere, passert testene og blitt godkjent i en pull-request.
• Designeren og utvikleren som er assignet til oppgaven er ansvarlige 
for å sørge for at bidraget er dokumentert i sine respektive områder,
 før det lanseres.

Utover dette synes jeg alt som allerede har blitt nevnt er helt supert. Så får vi trå på en fin linje (som team) for å finne balansen mellom hva som børe være absolutte krav, og hva som er "nice to haves".

[wkillerud]

Noen aksjonspunkter fra forum i dag 23.11:

• Legg inn overskrifter og andre hint om minstekrav til dokumentasjon i scaffold (@wkillerud)
• Legg inn i Figma-biblioteket som en page eller noe sånt (@onordbo)
• Oppdatere Utvikle for Jøkul med minstekravene. Lenke til gode eksempler. (@wkillerud)

Opprettet #2534 (meta)

[onordbo]

Lukket etter lansering #2534