Du kan have det bedste open source-projekt, men hvis det ikke har en god dokumentation, er der en risiko for, at det aldrig vil få succes. God dokumentation på kontoret gør, at du ikke behøver at besvare de samme spørgsmål igen og igen. Dokumentationen sikrer også, at folk kan forstå projektet, hvis nøgleressourcer forlader virksomheden, eller hvis roller ændres. Leve-gaitelines hjælper med at opretholde dataintegritet.
Hvis du har brug for at skrive en lang tekst, er Markdown et fremragende alternativ til HTML. Nogle gange er syntaksen i Markdown ikke tilstrækkelig. I så fald kan vi bruge HTML indeni det. For eksempel, tilpassede elementer. Så hvis du bygger et designsystem med native webkomponenter, kan de nemt inkluderes i den tekstlige dokumentation. Hvis du bruger React (eller en anden JSX-ramme som Preact eller Vue), kan du gøre det samme ved hjælp af MDX.
Denne artikel er en bred oversigt over værktøjer til at skrive dokumentation og oprette retningslinjer. Ikke alle værktøjer, der er nævnt her, bruger MDX, men det bliver i stigende grad integreret i dokumentationsværktøjer.
Hvad er MDX?
Fil .mdx har samme syntaks som Markdown, men gør det muligt at importere interaktive JSX-komponenter og integrere dem i dit indhold. Støtten til Vue-komponenter er i alfa. For at begynde at arbejde med MDX er det nok at installere "Create React App". Der findes plugins til Next.js og Gatsby. Den næste version af Docusaurus (version 2) vil også have indbygget støtte.
Skrivning af dokumentation med Docusaurus
Docusaurus er udviklet af Facebook. De bruger det i hvert open source-projekt undtagen React. Uden for virksomheden bruges det af Redux, Prettier, Gulp og Babel.
Projekter der bruger Docusaurus.
Docusaurus kan bruges til at skrive enhver dokumentation, ikke kun til frontend-beskrivelser. Det er bygget på React, men du behøver ikke at være bekendt med det for at bruge det. Det tager dine Markdown-filer, en smule magi, og så er godt struktureret, formateret og læsevenlig dokumentation med et smukt design klar.
På Redux's hjemmeside kan du se den standard Docusaurus skabelon.
Websites created with Docusaurus can also include a blog based on Markdown. Syntax highlighting is immediately enabled with Prism.js. Although Docusaurus has emerged relatively recently, it was recognized as the best tool of 2018 on StackShare.
Andre muligheder for oprettelse af indhold
Docusaurus er specifikt designet til at oprette dokumentation. Selvfølgelig er der en million og én måde at lave en hjemmeside på — du kan implementere din egen løsning på ethvert sprog, CMS eller bruge en statisk hjemmesidegenerator.
For eksempel bruger dokumentationen til React, IBMs designsystem, Apollo og Ghost CMS Gatsby — en statisk hjemmesidegenerator, der ofte anvendes til blogs. Hvis du arbejder med Vue, vil VuePress være et godt valg for dig. En anden mulighed er at bruge en generator skrevet i Python — MkDocs. Det er open source og konfigureres med en enkelt YAML-fil. GitBook er også et godt valg, men er kun gratis for åbne og ikke-kommercielle teams. Alternativt kan du bare uploade Markdown-filer ved at bruge Git og arbejde med dem i GitHub.
Dokumentering af komponenter: Docz, Storybook og Styleguidist
Retningslinjer, designsystemer, komponentbiblioteker — uanset hvad du kalder dem, er de blevet meget populære på det seneste. Fremkomsten af komponentbaserede rammer som React og de værktøjer, der er nævnt her, har gjort det muligt at forvandle dem fra blot et skud i tågen til nyttige værktøjer.
Storybook, Docz og Styleguidist gør det samme: de viser interaktive elementer og dokumenterer deres API. Et projekt kan have snesevis eller endda hundreder af komponenter — alle med forskellige tilstande og stilarter. Hvis du ønsker, at komponenterne skal genbruges, skal folk vide, at de eksisterer. Det er tilstrækkeligt at katalogisere komponenterne. Retningslinjerne giver et brugervenligt overblik over alle dine komponenter. Dette hjælper med at opretholde visuel konsistens og undgå dobbeltarbejde.
Disse værktøjer giver en bekvem måde at se forskellige tilstande på. Det kan være svært at genskabe hver tilstand af en komponent i konteksten af en reel applikation. I stedet for at klikke rundt i en reel app, bør du udvikle en separat komponent. Det er muligt at simulere svære tilstande (f.eks. indlæsningsstatus).
Sammen med den visuelle demonstration af forskellige tilstande og en liste over egenskaber er det ofte nødvendigt at skrive en generel beskrivelse af indholdet — begrundelse for designet, anvendelsesscenarier eller beskrivelse af resultaterne fra brugertests. Markdown er meget enkelt at lære — ideelt set bør retningslinjerne være en fælles ressource for designere og udviklere. Docz, Styleguidist og Storybook tilbyder en måde at nemt blande Markdown med komponenter.
Docz
Docz fungerer i øjeblikket kun med React, men der arbejdes aktivt på at understøtte Preact, Vue og webkomponenter. Docz er den nyeste af de tre værktøjer, men har formået at samle over 14.000 stjerner på GitHub. Docz præsenterer to komponenter — <Playground> og < Props >. De importeres og bruges i filer .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Du kan _skrive_ **markdown**
### Du kan importere og bruge komponenter
Du kan indpakke dine egne React-komponenter med <Playground>, for at skabe en tilsvarende indbygget CodePen eller CodeSandbox — det vil sige, du kan se din komponent og redigere den.
<Props> vil vise alle tilgængelige egenskaber for den givne React-komponent, standardværdier og om en egenskab er påkrævet.
<Props of={Button} />Personligt mener jeg, at denne tilgang baseret på MDX er den nemmeste at forstå og den nemmeste at arbejde med.
Hvis du er fan af statisk webside-generator Gatsby, tilbyder Docz fremragende integration.
Styleguidist
Som i Docz skrives eksemplerne ved hjælp af Markdown-syntaks. Styleguidist bruger Markdown-kodeblokke (trippel citattegn) i almindelige filer .md filer, ikke i MDX.
```js
Kodeblokke i Markdown viser normalt bare koden. Når du bruger Styleguidist, vil enhver kodeblok med sprog-tag js, jsx eller javascript blive vist som en React-komponent. Som i Docz er koden redigerbar — du kan ændre egenskaber og se resultatet med det samme.
Styleguidist vil automatisk oprette en tabel over egenskaber fra PropTypes, Flow eller Typescript erklæringer.
Styleguidist understøtter nu React og Vue.
Storybook
Storybook positionerer sig som "miljøet for udvikling af UI-komponenter". I stedet for at skrive eksempler på komponenter inden for Markdown- eller MDX-filer, skriver du dem inden for Javascript-filer. Historik dokumentere en specifik tilstand af komponenten. For eksempel kan en komponent have historier for indlæsningsstatus og deaktiveret status (deaktiveret).
storiesOf('Button', module)
.add('deaktiveret', () => (
))Storybook er langt mere kompliceret end Styleguidist og Docz. Men det er samtidig det mest populære valg, med over 36.000 stjerner på Github. Det er et open source-projekt, der har 657 bidragydere og vedligeholdes af ansatte. Det bruges af Airbnb, Algolia, Atlassian, Lyft og Salesforce. Storybook understøtter flere rammer end konkurrenterne — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte og almindelig HTML.
I den kommende udgave vil der være funktioner fra Docz og MDX blive integreret.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nye funktioner i Storybook vil gradvist blive tilgængelige i løbet af de næste par måneder, og det ser ud til at være et stort skridt fremad.
Resumé
Fordelene ved mønsterbiblioteker fremhæves i millioner af artikler på Medium. Når alt er gjort godt, letter de oprettelsen af relaterede produkter og vedligeholdelsen af identitet. Selvfølgelig vil ingen af disse værktøjer magisk skabe et designsystem. Det kræver omhyggelig designplanlægning og CSS. Men når tiden kommer til at gøre designsystemet tilgængeligt for hele virksomheden, er Docz, Storybook og Styleguidist fremragende muligheder.
Fra oversætteren. Dette er min første erfaring på Habr. Hvis du finder nogen unøjagtigheder, eller har forslag til forbedringer af artiklen — skriv til mig.
Kilde: habr.com
