Môžete mať najlepší open source projekt, ale ak nemá dobrú dokumentáciu, je pravdepodobné, že sa nikdy nerozbehne. V kancelárii vám dobrá dokumentácia zabráni odpovedať na rovnaké otázky. Dokumentácia tiež zaisťuje, že ľudia môžu pochopiť projekt, ak kľúčoví zamestnanci opustia spoločnosť alebo sa zmenia roly. Životné pokyny pomôžu zabezpečiť integritu údajov.
Ak potrebujete napísať dlhý text, Markdown je skvelá alternatíva k HTML. Niekedy syntax Markdown nestačí. V tomto prípade môžeme použiť HTML vnútri. Napríklad vlastné prvky. Ak teda budujete dizajnový systém s natívnymi webovými komponentmi, dajú sa jednoducho zahrnúť do textovej dokumentácie. Ak používate React (alebo akýkoľvek iný rámec JSX ako Preact alebo Vue), môžete urobiť to isté s MDX.
Tento článok je širokým prehľadom nástrojov na písanie dokumentácie a vytváranie pokynov. Nie všetky nástroje, ktoré sú tu uvedené, používajú MDX, ale čoraz viac sa používa v dokumentačných nástrojoch.
čo je MDX?
súbor .mdx má rovnakú syntax ako Markdown, ale umožňuje vám importovať interaktívne komponenty JSX a vložiť ich do vášho obsahu. Podpora komponentov Vue je vo verzii alfa. Ak chcete začať pracovať s MDX, stačí nainštalovať „Create React App“. Existujú pluginy pre Next.js a Gatsby. Ďalšia verzia Docusaurus (verzia 2) bude mať tiež natívnu podporu.
Písanie dokumentácie s Docusaurusom
Docusaurus napísal na Facebooku. Používajú ho na každom open source projekte okrem Reactu. Mimo spoločnosti ho používajú Redux, Prettier, Gulp a Babel.
Projekty, ktoré využívajú Docusaurus.
Docusaurus sa dá použiť na písanie každý dokumentáciu, nielen na popis frontendu. Má pod kapotou React, no na používanie ho nemusíte poznať. Zaberie vaše súbory Markdown, štipku mágie a dobre štruktúrovaná, naformátovaná a čitateľná dokumentácia s krásnym dizajnom je pripravená.
Na webovej stránke Redux si môžete pozrieť štandardnú šablónu Docusaurus
Webové stránky vytvorené pomocou Docusaurus môžu zahŕňať aj blog založený na Markdown. Prism.js je okamžite pripojený na zvýraznenie syntaxe. Napriek tomu, že sa Docusaurus objavil relatívne nedávno, bol na StackShare uznaný ako najlepší nástroj roku 2018.
Ďalšie možnosti tvorby obsahu
Docusaurus je špeciálne navrhnutý na vytváranie dokumentácie. Samozrejme, existuje milión a jeden spôsobov, ako urobiť webovú stránku – môžete nasadiť vlastné riešenie v akomkoľvek jazyku, CMS, alebo použiť generátor statických stránok.
Napríklad dokumentácia pre React, dizajnový systém IBM, Apollo a Ghost CMS používa Gatsby – generátor statických stránok, ktorý sa často používa pre blogy. Ak pracujete s Vue, potom je pre vás VuePress dobrou voľbou. Ďalšou možnosťou je použiť generátor napísaný v Pythone – MkDocs. Je to open source a konfiguruje sa pomocou jedného súboru YAML. GitBook je tiež dobrá voľba, ale je zadarmo len pre verejné a nekomerčné tímy. Môžete tiež jednoducho nahrať súbory mardown pomocou Git a pracovať s nimi v Github.
Dokumentačné komponenty: Docz, Storybook a Styleguidist
Smernice, návrh systému, knižnice komponentov – akokoľvek to nazvete, v poslednej dobe sa to stalo veľmi populárnym. Príchod komponentov, ako je React a tu spomenuté nástroje, ich premenil z márnivých projektov na užitočné nástroje.
Storybook, Docz a Styleguidist robia to isté: zobrazujú interaktívne prvky a dokumentujú ich API. Projekt môže mať desiatky alebo dokonca stovky komponentov – všetky s rôznymi stavmi a štýlmi. Ak chcete, aby sa komponenty znovu použili, ľudia musia vedieť, že existujú. Ak to chcete urobiť, jednoducho katalogizujte komponenty. Pokyny poskytujú prehľad o všetkých vašich komponentoch, ktoré je možné ľahko nájsť. Pomáha to zachovať vizuálnu konzistenciu a vyhnúť sa opakovanej práci.
Tieto nástroje poskytujú pohodlný spôsob zobrazenia rôznych stavov. Môže byť ťažké reprodukovať každý stav komponentu v kontexte skutočnej aplikácie. Namiesto klikania na skutočnú aplikáciu sa oplatí vyvinúť samostatný komponent. Je možné simulovať ťažko dostupné stavy (napríklad stavy zaťaženia).
Spolu s názornou ukážkou rôznych stavov a zoznamom vlastností je často potrebné napísať aj všeobecný popis obsahu – zdôvodnenie návrhu, prípady použitia alebo popisy výsledkov používateľského testovania. Markdown sa dá veľmi ľahko naučiť – v ideálnom prípade by usmernenia mali byť zdieľaným zdrojom pre dizajnérov a vývojárov. Docz, Styleguidist a Storybook ponúkajú spôsob, ako jednoducho zmiešať Markdown s komponentmi.
Docz
V súčasnosti Docz pracuje iba s Reactom, ale aktívne sa pracuje na podpore Preact, Vue a webových komponentov. Docz je najnovší z troch nástrojov, ale podarilo sa mu nazbierať viac ako 14 000 hviezdičiek na Github. Docz zavádza dve zložky − <Playground> и < Props >. Sú importované a používané v súboroch .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Môžete zabaliť svoje vlastné komponenty Reactu <Playground>na vytvorenie analógu vstavaného CodePen alebo CodeSandbox - to znamená, že vidíte svoj komponent a môžete ho upravovať.
<Playground>
<Button>click</Button>
</Playground><Props> zobrazí všetky dostupné vlastnosti pre daný komponent React, predvolené hodnoty a či je vlastnosť vyžadovaná.
<Props of={Button} />Osobne považujem tento prístup založený na MDX za najjednoduchší na pochopenie a najjednoduchšiu prácu s ním.
Ak ste fanúšikom generátora statických stránok Gatsby, Docz ponúka skvelú integráciu.
Sprievodca štýlom
Podobne ako Docz, aj príklady sú napísané pomocou syntaxe Markdown. Styleguidist používa bloky kódu Markdown (trojité úvodzovky) v bežných súboroch .md súbory, nie MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Bloky kódu v Markdown zvyčajne len zobrazujú kód. Pri použití Styleguidist akýkoľvek blok kódu s jazykovou značkou js, jsx alebo javascript sa vykreslí ako komponent React. Rovnako ako Docz, kód je upraviteľný - môžete zmeniť vlastnosti a okamžite vidieť výsledok.
Styleguidist automaticky vytvorí tabuľku vlastností z deklarácií PropTypes, Flow alebo Typescript.
Styleguidist momentálne podporuje React a Vue.
kniha rozprávok
Storybook sa stavia ako „vývojové prostredie komponentov používateľského rozhrania“. Namiesto zapisovania vzorových komponentov do súborov Markdown alebo MDX, píšete príbehy v súboroch Javascript. Príbeh dokumentovať konkrétny stav komponentu. Komponent môže mať napríklad históriu pre stav načítania a stav vypnutia (invalidný).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Príbehová kniha je oveľa komplexnejšia ako Styleguidist a Docz. Zároveň je to však najobľúbenejšia možnosť, projekt má na Githube viac ako 36 000 hviezdičiek. Ide o open source projekt s 657 prispievateľmi a zamestnancami na plný úväzok. Používajú ho Airbnb, Algolia, Atlassian, Lyft a Salesforce. Storybook podporuje viac rámcov ako konkurencia – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte a bežné HTML.
V budúcom vydaní budú predstavené funkcie od Docz a MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nové funkcie Storybooku sa budú zavádzať postupne v priebehu niekoľkých nasledujúcich mesiacov a zdá sa, že to bude veľký krok vpred.
Výsledky
Výhody knižnice vzorov sú vyzdvihované v miliónoch článkov na Medium. Keď sú dobre vykonané, uľahčujú vytváranie súvisiacich produktov a udržiavanie identity. Samozrejme, žiadny z týchto nástrojov magicky nevytvorí dizajnový systém. To si vyžaduje starostlivý dizajn a CSS. Ale keď príde čas sprístupniť dizajnový systém celej spoločnosti, Docz, Storybook a Styleguidist sú skvelé možnosti.
Od prekladateľa. Toto je moja prvá skúsenosť na Habré. Ak nájdete nejaké nepresnosti, alebo máte návrhy na zlepšenie článku, napíšte mi do osobnej správy.
Zdroj: hab.com