Dir hutt vläicht e besseren Open Source-Projet, awer wann et keng gutt Dokumentatioun huet, sinn d'Chancen datt et ni ofhëlt. Am Büro wäert gutt Dokumentatioun Iech verhënneren datt Dir déiselwecht Froen ëmmer erëm beäntwert. D'Dokumentatioun garantéiert och datt d'Leit Sënn vum Projet kënne maachen wann Schlëssel Mataarbechter d'Firma verloossen oder d'Roll änneren. Live Richtlinnen hëllefen d'Datenintegritéit ze garantéieren.
Wann Dir laangen Text schreiwen musst, ass Markdown eng super Alternativ zu HTML. Heiansdo ass d'Markdown Syntax net genuch. An dësem Fall kënne mir HTML dobannen benotzen. Zum Beispill, Benotzerdefinéiert Elementer. Dofir, wann Dir en Designsystem mat gebiertege Webkomponenten baut, ass et einfach se an Textdokumentatioun opzehuelen. Wann Dir React benotzt (oder all aner JSX Kader wéi Preact oder Vue), kënnt Dir datselwecht mat MDX maachen.
Dësen Artikel ass e breeden Iwwerbléck iwwer Tools fir Dokumentatioun ze schreiwen an eng Richtlinn ze kreéieren. Net all Tools, déi hei opgelëscht sinn, benotzen MDX, awer et gëtt ëmmer méi an Dokumentatiounsinstrumenter abegraff.
Wat ass MDX?
Fichier .mdx huet déiselwecht Syntax wéi Markdown awer erlaabt Iech interaktiv JSX Komponenten z'importéieren an se an Ären Inhalt z'integréieren. Ënnerstëtzung fir Vue Komponente ass an Alpha. Fir mat MDX ze schaffen, installéiere just "Create React App". Et gi Plugins fir Next.js a Gatsby. Déi nächst Versioun vum Docusaurus (Versioun 2) wäert och agebaute Support hunn.
Schreiwen Dokumentatioun mat Docusaurus
Docusaurus huet op Facebook geschriwwen. Si benotzen et op all Open Source Projet ausser React. Ausserhalb vun der Firma benotzen Redux, Prettier, Gulp a Babel et.
Projeten déi Docusaurus benotzen.
Docusaurus ka benotzt ginn fir ze schreiwen iergendeen Dokumentatioun, net nëmme fir de Frontend ze beschreiwen. Et huet React ënner der Hood, awer Dir musst et net vertraut sinn fir se ze benotzen. Et hëlt Är Markdown Dateien, eng Prise Magie a gutt strukturéiert, formatéiert a liesbar Dokumentatioun mat engem schéine Design ass prett.
Dir kënnt de Standard Docusaurus Schabloun op der Redux Websäit gesinn.
Siten gebaut mat Docusaurus kënnen och e Markdown-baséiert Blog enthalen. Fir Syntax Highlight gëtt Prism.js direkt abegraff. Trotz der Tatsaach, datt Docusaurus relativ viru kuerzem opgetaucht ass, gouf et als dat bescht Tool vun 2018 op StackShare unerkannt.
Aner Inhalt Creatioun Optiounen
Docusaurus ass speziell entwéckelt fir Dokumentatioun ze kreéieren. Natierlech ginn et eng Millioun an eng Manéier fir eng Websäit ze maachen - Dir kënnt Är eege Léisung an all Sprooch, CMS, oder e statesche Site Generator benotzen.
Zum Beispill, d'Dokumentatioun fir React, den IBM Design System, Apollo, a Ghost CMS benotzen Gatsby, e statesche Site Generator dacks fir Blogs benotzt. Wann Dir mat Vue schafft, dann ass VuePress eng gutt Optioun fir Iech. Eng aner Optioun ass e Generator ze benotzen geschriwwen am Python - MkDocs. Et ass op a konfiguréiert mat enger eenzeger YAML Datei. GitBook ass och eng gutt Optioun, awer et ass nëmme gratis fir oppen an net-kommerziell Teams. Dir kënnt och just Mardown Dateien mat Git eroplueden a mat hinnen am Github schaffen.
Komponentdokumentatioun: Docz, Storybook a Styleguidist
Richtlinnen, Systemdesign, Komponentbibliothéiken, wéi och ëmmer Dir wëllt se nennen, dës sinn zënter kuerzem ganz populär ginn. D'Entstoe vu Komponente Frameworks wéi React an déi hei erwähnt Tools huet et méiglech gemaach se vun Vanity Projeten an nëtzlech Tools ze transforméieren.
Storybook, Docz a Styleguidist maachen datselwecht: interaktiv Elementer weisen an hir API dokumentéieren. E Projet kann Dosende oder souguer Honnerte vu Komponenten hunn, all mat verschiddene Staaten a Stiler. Wann Dir wëllt datt Komponente weiderbenotzt ginn, mussen d'Leit wëssen datt se existéieren. Fir dëst ze maachen, ass et genuch fir d'Komponenten ze katalogiséieren. Richtlinnen bidden en einfach ze sichen Iwwerbléck vun all Är Komponenten. Dëst hëlleft visuell Konsequenz ze halen an repetitive Aarbecht ze vermeiden.
Dës Tools bidden e praktesche Wee fir verschidde Staaten ze gesinn. Et kann schwéier sinn all Staat vun enger Komponent am Kontext vun enger realer Applikatioun ze replizéieren. Amplaz op déi aktuell Applikatioun ze klicken, ass et derwäert eng separat Komponent z'entwéckelen. Et ass méiglech schwéier z'erreechen Staaten ze modelléieren (zum Beispill Luedestaat).
Zesumme mat enger visueller Demonstratioun vu verschiddene Staaten an enger Lëscht vun Eegeschaften ass et dacks néideg eng allgemeng Beschreiwung vum Inhalt ze schreiwen - Designrationalen, Benotzungsfäll oder eng Beschreiwung vun de Resultater vum Benotzertest. Markdown ass ganz einfach ze léieren - am Idealfall sollten Richtlinnen eng gemeinsam Ressource fir Designer an Entwéckler sinn. Docz, Styleguidist, a Storybook bidden e Wee fir Markdown mat Komponenten einfach ze vermëschen.
Docz
De Moment funktionnéiert Docz nëmme mat React, awer schafft aktiv un Ënnerstëtzung fir Preact, Vue, a Web Komponenten. Docz ass déi lescht vun den dräi Tools, awer konnt iwwer 14 Stären op Github sammelen. Docz féiert zwee Komponenten - <Playground> и < Props >. Si ginn importéiert a benotzt an Dateien .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Dir kënnt Är eege React Komponenten mat wéckelen <Playground>fir en Analog vum agebaute CodePen oder CodeSandbox ze kreéieren - dat ass, Dir gesitt Äre Komponent a kënnt et änneren.
<Playground>
<Button>click</Button>
</Playground><Props> wäert all verfügbar Eegeschafte fir de gegebene React Komponent weisen, Standardwäerter an ob d'Propriétéit erfuerderlech ass.
<Props of={Button} />Perséinlech fannen ech dës MDX-baséiert Approche am einfachsten ze verstoen an am einfachsten mat ze schaffen.
Wann Dir e Fan vum Gatsby sengem statesche Site Generator sidd, bitt Docz super Integratiounen.
style guidist
Wéi an Docz, Beispiller gi mat Markdown Syntax geschriwwen. Styleguidist benotzt Markdown Code Blocks (Triple Zitater) a reguläre Dateien .md Dateien, net an MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Code Blocks am Markdown weisen normalerweis just de Code. Wann Dir Styleguidist benotzt, all Block vu Code mat engem Sproochetag js, jsx oder javascript wäert als React Komponent ofginn. Wéi Docz ass de Code editéierbar - Dir kënnt Eegeschaften änneren an direkt d'Resultat gesinn.
Styleguidist erstellt automatesch e Property Blat aus PropTypes, Flow oder Typescript Deklaratiounen.
Styleguidist ënnerstëtzt elo React a Vue.
Erzielbuch
Storybook rechnt sech als "UI Komponent Entwécklung Ëmfeld". Amplaz Komponentbeispiele bannent Markdown oder MDX Dateien ze schreiwen, schreift Dir Geschichten bannent Javascript Fichieren. Geschicht Dokument de spezifeschen Zoustand vun enger Komponent. Zum Beispill kann e Komponent Geschichte fir e Luedezoustand an e behënnerte Staat hunn (Behënnerten).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook ass vill méi komplex wéi Styleguidist an Docz. Awer gläichzäiteg ass dëst déi populärste Optioun, op Github huet de Projet méi wéi 36 Stären. Dëst ass en Open Source Projet mat 000 Mataarbechter a Begleedung vum Personal. Et gëtt vun Airbnb, Algolia, Atlassian, Lyft a Salesforce benotzt. Storybook ënnerstëtzt méi Kaderen wéi d'Konkurrenz - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, a Einfach HTML.
An enger zukünfteg Verëffentlechung ginn et Chips vun Docz an MDX gëtt agefouert.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Déi nei Storybook Feature wäerten an den nächste Méint lues a lues ausrollen, an et gesäit aus wéi wann et e grousse Schrëtt no vir wäert sinn.
Resultater
D'Virdeeler vun der Musterbibliothéik ginn a Millioune Artikelen op Medium gelueft. Wann et gutt gemaach gëtt, maachen se et méi einfach fir verwandte Produkter ze kreéieren an eng Identitéit z'erhalen. Natierlech wäert keng vun dësen Tools magesch en Designsystem erstellen. Dëst erfuerdert virsiichteg Design an CSS Design. Awer wann et Zäit ass den Designsystem fir d'ganz Firma verfügbar ze maachen, Docz, Storybook a Styleguidist si super Optiounen.
Vun engem Iwwersetzer. Dëst ass meng éischt Erfahrung op Habré. Wann Dir keng Ongenauegkeeten fannt, oder Suggestioune fir den Artikel ze verbesseren - schreift an engem perséinlechen.
Source: will.com