Du kan ha det beste åpen kildekode-prosjektet, men hvis det ikke har god dokumentasjon, er sjansen stor for at det aldri tar av. På kontoret vil god dokumentasjon hindre deg i å svare på de samme spørsmålene. Dokumentasjon sikrer også at folk kan forstå prosjektet dersom nøkkelmedarbeidere forlater bedriften eller rollene endres. Levende retningslinjer vil bidra til å sikre dataintegritet.
Hvis du trenger å skrive lang tekst, er Markdown et flott alternativ til HTML. Noen ganger er ikke Markdown-syntaks nok. I dette tilfellet kan vi bruke HTML i den. For eksempel tilpassede elementer. Derfor, hvis du bygger et designsystem med native webkomponenter, kan de enkelt inkluderes i tekstdokumentasjonen. Hvis du bruker React (eller et annet JSX-rammeverk som Preact eller Vue), kan du gjøre det samme med MDX.
Denne artikkelen er en bred oversikt over verktøy for å skrive dokumentasjon og lage retningslinjer. Ikke alle verktøyene som er oppført her bruker MDX, men det blir i økende grad inkludert i dokumentasjonsverktøy.
Hva er MDX?
fil .mdx har samme syntaks som Markdown, men lar deg importere interaktive JSX-komponenter og bygge dem inn i innholdet ditt. Støtte for Vue-komponenter er i alfa. For å begynne å jobbe med MDX, installer bare "Create React App". Det finnes plugins for Next.js og Gatsby. Den neste versjonen av Docusaurus (versjon 2) vil også ha innebygd støtte.
Skrive dokumentasjon med Docusaurus
Docusaurus skrev på Facebook. De bruker det på alle åpen kildekode-prosjekter bortsett fra React. Utenfor selskapet brukes den av Redux, Prettier, Gulp og Babel.
Prosjekter som bruker Docusaurus.
Docusaurus kan brukes til å skrive noen dokumentasjon, ikke bare for å beskrive frontend. Den har React under panseret, men du trenger ikke være kjent med den for å bruke den. Det tar Markdown-filene dine, en klype magi og velstrukturert, formatert og lesbar dokumentasjon med vakkert design er klar.
På Redux-nettstedet kan du se standard Docusaurus-malen
Nettsteder bygget med Docusaurus kan også inkludere en Markdown-basert blogg. Prism.js kobles umiddelbart til for syntaksutheving. Til tross for at Docusaurus dukket opp relativt nylig, ble den anerkjent som det beste verktøyet i 2018 på StackShare.
Andre alternativer for innholdsoppretting
Docusaurus er spesielt utviklet for å lage dokumentasjon. Selvfølgelig er det en million og én måter å lage et nettsted på - du kan distribuere din egen løsning på et hvilket som helst språk, CMS, eller bruke en statisk nettstedsgenerator.
For eksempel bruker dokumentasjon for React, IBM designsystem, Apollo og Ghost CMS Gatsby – en statisk nettstedsgenerator som ofte brukes til blogger. Hvis du jobber med Vue, er VuePress et godt alternativ for deg. Et annet alternativ er å bruke en generator skrevet i Python - MkDocs. Den er åpen kildekode og konfigurert ved hjelp av en enkelt YAML-fil. GitBook er også et godt alternativ, men det er bare gratis for offentlige og ikke-kommersielle team. Du kan også enkelt laste opp mardown-filer ved hjelp av Git og jobbe med dem i Github.
Dokumentere komponenter: Docz, Storybook og Styleguidist
Retningslinjer, systemdesign, komponentbiblioteker – uansett hva du kaller dem, har det blitt veldig populært i det siste. Fremkomsten av komponentrammeverk som React og verktøyene nevnt her har forvandlet dem fra forfengelighetsprosjekter til nyttige verktøy.
Storybook, Docz og Styleguidist gjør alle det samme: viser interaktive elementer og dokumenterer deres API. Et prosjekt kan ha dusinvis eller til og med hundrevis av komponenter - alle med forskjellige tilstander og stiler. Hvis du vil at komponenter skal gjenbrukes, må folk vite at de eksisterer. For å gjøre dette, katalogiser komponentene. Retningslinjer gir en oversikt over alle komponentene dine som er lett å finne. Dette bidrar til å opprettholde visuell konsistens og unngå repeterende arbeid.
Disse verktøyene gir en praktisk måte å se forskjellige tilstander på. Det kan være vanskelig å reprodusere hver tilstand av en komponent i sammenheng med en reell applikasjon. I stedet for å klikke på selve applikasjonen, er det verdt å utvikle en egen komponent. Vanskelig tilgjengelige tilstander (som lastetilstander) kan simuleres.
Sammen med en visuell demonstrasjon av ulike tilstander og en liste over egenskaper, er det ofte nødvendig å skrive en generell beskrivelse av innholdet – designrasjonaler, brukstilfeller eller beskrivelser av brukertestresultater. Markdown er veldig enkelt å lære - ideelt sett bør retningslinjer være en delt ressurs for designere og utviklere. Docz, Styleguidist og Storybook tilbyr en måte å enkelt blande Markdown med komponenter.
Docz
Foreløpig jobber Docz kun med React, men aktivt arbeid pågår for å støtte Preact, Vue og webkomponenter. Docz er det nyeste av de tre verktøyene, men det har klart å samle over 14 000 stjerner på Github. Docz introduserer to komponenter − <Playground> и < Props >. De importeres og brukes i filer .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Du kan pakke inn dine egne React-komponenter med <Playground>for å lage en analog av den innebygde CodePen eller CodeSandbox - det vil si at du ser komponenten din og kan redigere den.
<Playground>
<Button>click</Button>
</Playground><Props> vil vise alle tilgjengelige egenskaper for en gitt React-komponent, standardverdier og om egenskapen er nødvendig.
<Props of={Button} />Personlig synes jeg denne MDX-baserte tilnærmingen er den enkleste å forstå og den enkleste å jobbe med.
Hvis du er en fan av Gatsby statiske nettstedsgenerator, tilbyr Docz en flott integrasjon.
Stilguide
Som Docz, er eksempler skrevet med Markdown-syntaks. Styleguidist bruker Markdown-kodeblokker (trippel anførselstegn) i vanlige filer .md filer, ikke MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Kodeblokker i Markdown viser vanligvis bare kode. Når du bruker Styleguidist, en hvilken som helst kodeblokk med en språkkode js, jsx eller javascript vil gjengi som en React-komponent. Som Docz er koden redigerbar - du kan endre egenskaper og umiddelbart se resultatet.
Styleguidist vil automatisk opprette en egenskapstabell fra PropTypes, Flow eller Typescript-deklarasjoner.
Styleguidist støtter for tiden React og Vue.
Storybook
Storybook posisjonerer seg som et "UI-komponentutviklingsmiljø." I stedet for å skrive eksempelkomponenter inne i Markdown- eller MDX-filer, skriver du historie inne i Javascript-filer. Story dokumentere den spesifikke tilstanden til en komponent. For eksempel kan en komponent ha historier for en lastet tilstand og en deaktivert tilstand (deaktivert).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook er mye mer kompleks enn Styleguidist og Docz. Men samtidig er dette det mest populære alternativet; prosjektet har mer enn 36 000 stjerner på Github. Det er et åpen kildekode-prosjekt med 657 bidragsytere og heltidsansatte. Den brukes av Airbnb, Algolia, Atlassian, Lyft og Salesforce. Storybook støtter flere rammeverk enn konkurrenter - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte og vanlig HTML.
I en fremtidig utgivelse vil det være funksjoner fra Docz og MDX vil bli introdusert.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Storybooks nye funksjoner vil rulle ut gradvis i løpet av de neste månedene, og det ser ut til at det vil være et stort skritt fremover.
Resultater av
Fordelene med et mønsterbibliotek blir hyllet i millioner av artikler på Medium. Når de gjøres godt, gjør de det lettere å lage relaterte produkter og opprettholde identitet. Selvfølgelig vil ingen av disse verktøyene på magisk vis lage et designsystem. Dette krever nøye design og CSS. Men når det er på tide å gjøre et designsystem tilgjengelig for hele selskapet, er Docz, Storybook og Styleguidist gode alternativer.
Fra oversetteren. Dette er min første opplevelse på Habré. Hvis du finner noen unøyaktigheter, eller har forslag til forbedring av artikkelen, skriv til meg i en personlig melding.
Kilde: www.habr.com