Můžete mít ten nejlepší open source projekt, ale pokud nemá dobrou dokumentaci, je pravděpodobné, že nikdy nevzlétne. V kanceláři vám dobrá dokumentace zabrání odpovídat na stejné otázky. Dokumentace také zajišťuje, že lidé mohou pochopit projekt, pokud klíčoví zaměstnanci opustí společnost nebo se změní role. Životní pokyny pomohou zajistit integritu dat.
Pokud potřebujete psát dlouhý text, Markdown je skvělá alternativa k HTML. Někdy syntaxe Markdown nestačí. V tomto případě můžeme použít HTML uvnitř. Například vlastní prvky. Pokud tedy budujete designový systém s nativními webovými komponentami, lze je snadno zahrnout do textové dokumentace. Pokud používáte React (nebo jakýkoli jiný rámec JSX, jako je Preact nebo Vue), můžete totéž udělat s MDX.
Tento článek je širokým přehledem nástrojů pro psaní dokumentace a vytváření pokynů. Ne všechny zde uvedené nástroje používají MDX, ale stále častěji je součástí dokumentačních nástrojů.
Co je MDX?
Soubor .mdx má stejnou syntaxi jako Markdown, ale umožňuje importovat interaktivní komponenty JSX a vkládat je do obsahu. Podpora komponent Vue je v alfa verzi. Chcete-li začít pracovat s MDX, stačí nainstalovat „Create React App“. Existují pluginy pro Next.js a Gatsby. Další verze Docusaurus (verze 2) bude mít také nativní podporu.
Psaní dokumentace s Docusaurus
Docusaurus napsal na Facebooku. Používají ho na každém open source projektu kromě Reactu. Mimo společnost jej používají Redux, Prettier, Gulp a Babel.
Projekty využívající Docusaurus.
Docusaurus lze použít k psaní každý dokumentaci, nejen k popisu frontendu. Má pod kapotou React, ale pro jeho použití ho nemusíte znát. Vezme vaše soubory Markdown, špetku magie a dobře strukturovanou, formátovanou a čtivou dokumentaci s krásným designem je připravena.
Na webu Redux si můžete prohlédnout standardní šablonu Docusaurus
Webové stránky vytvořené pomocí Docusaurus mohou také obsahovat blog založený na Markdown. Prism.js je okamžitě připojen pro zvýraznění syntaxe. Navzdory skutečnosti, že se Docusaurus objevil relativně nedávno, byl na StackShare uznán jako nejlepší nástroj roku 2018.
Další možnosti tvorby obsahu
Docusaurus je speciálně navržen pro vytváření dokumentace. Samozřejmě existuje milion a jeden způsobů, jak udělat web – můžete nasadit vlastní řešení v jakémkoli jazyce, CMS nebo použít generátor statických stránek.
Například dokumentace pro React, návrhový systém IBM, Apollo a Ghost CMS používá Gatsby – generátor statických stránek, který se často používá pro blogy. Pokud pracujete s Vue, pak je pro vás VuePress dobrou volbou. Další možností je použít generátor napsaný v Pythonu – MkDocs. Je to open source a konfiguruje se pomocí jediného souboru YAML. GitBook je také dobrá volba, ale je zdarma pouze pro veřejné a nekomerční týmy. Můžete také jednoduše nahrát soubory mardown pomocí Git a pracovat s nimi v Github.
Dokumentační komponenty: Docz, Storybook a Styleguidist
Pokyny, návrh systému, knihovny komponent – ať už to nazvete jakkoli, v poslední době se to stalo velmi populární. Příchod komponentových rámců, jako je React a zde zmíněné nástroje, je přeměnil z marných projektů na užitečné nástroje.
Storybook, Docz a Styleguidist dělají totéž: zobrazují interaktivní prvky a dokumentují jejich API. Projekt může mít desítky nebo dokonce stovky komponent – všechny s různými stavy a styly. Pokud chcete, aby byly komponenty znovu použity, lidé musí vědět, že existují. Chcete-li to provést, jednoduše katalogizujte komponenty. Pokyny poskytují snadno dostupný přehled všech vašich komponent. To pomáhá zachovat vizuální konzistenci a vyhnout se opakované práci.
Tyto nástroje poskytují pohodlný způsob zobrazení různých stavů. Může být obtížné reprodukovat každý stav komponenty v kontextu skutečné aplikace. Místo klikání na skutečnou aplikaci se vyplatí vyvinout samostatnou komponentu. Lze simulovat těžko dostupné stavy (např. stavy zatížení).
Spolu s vizuální ukázkou různých stavů a seznamem vlastností je často nutné napsat obecný popis obsahu – zdůvodnění návrhu, případy použití nebo popisy výsledků uživatelského testování. Markdown je velmi snadné se naučit – v ideálním případě by pokyny měly být sdíleným zdrojem pro designéry a vývojáře. Docz, Styleguidist a Storybook nabízejí způsob, jak snadno kombinovat Markdown s komponentami.
Docz
V současné době Docz pracuje pouze s Reactem, ale aktivně se pracuje na podpoře Preact, Vue a webových komponent. Docz je nejnovější ze tří nástrojů, ale podařilo se mu nasbírat přes 14 000 hvězdiček na Githubu. Docz zavádí dvě složky − <Playground> и < Props >. Jsou importovány a použity v souborech .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 zabalit své vlastní komponenty Reactu <Playground>vytvořit analog vestavěného CodePen nebo CodeSandbox - to znamená, že vidíte svou komponentu a můžete ji upravovat.
<Playground>
<Button>click</Button>
</Playground><Props> zobrazí všechny dostupné vlastnosti pro danou komponentu React, výchozí hodnoty a zda je vlastnost vyžadována.
<Props of={Button} />Osobně považuji tento přístup založený na MDX za nejsnáze pochopitelný a nejsnáze se s ním pracuje.
Pokud jste fanouškem generátoru statických stránek Gatsby, Docz nabízí skvělou integraci.
Průvodce stylem
Stejně jako Docz jsou příklady psány pomocí syntaxe Markdown. Styleguidist používá bloky kódu Markdown (trojité uvozovky) v běžných souborech .md soubory, nikoli MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Bloky kódu v Markdown obvykle pouze zobrazují kód. Při použití Styleguidist jakýkoli blok kódu se značkou jazyka js, jsx nebo javascript se vykreslí jako komponenta React. Stejně jako Docz je kód upravitelný - můžete změnit vlastnosti a okamžitě vidět výsledek.
Styleguidist automaticky vytvoří tabulku vlastností z deklarací PropTypes, Flow nebo Typescript.
Styleguidist aktuálně podporuje React a Vue.
Příběh
Storybook se staví jako „prostředí pro vývoj komponent uživatelského rozhraní“. Namísto psaní ukázkových komponent do souborů Markdown nebo MDX zapisujete příběhy uvnitř souborů Javascript. Příběh dokumentovat konkrétní stav součásti. Komponenta může mít například historii pro načtený stav a zakázaný stav (invalidní).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook je mnohem komplexnější než Styleguidist a Docz. Ale zároveň je to nejoblíbenější možnost, projekt má na Githubu více než 36 000 hvězdiček. Jedná se o open source projekt s 657 přispěvateli a zaměstnanci na plný úvazek. Používají ho Airbnb, Algolia, Atlassian, Lyft a Salesforce. Storybook podporuje více frameworků než konkurence – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte a běžné HTML.
V budoucí verzi budou funkce od Docz a budou představeny MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nové funkce Storybooku budou postupně zaváděny během několika příštích měsíců a vypadá to, že to bude velký krok vpřed.
Výsledky
Výhody knihovny vzorů jsou vychvalovány v milionech článků na Medium. Když jsou dobře provedeny, usnadňují vytváření souvisejících produktů a udržování identity. Samozřejmě, že žádný z těchto nástrojů magicky nevytvoří designový systém. To vyžaduje pečlivý design a CSS. Když ale přijde čas zpřístupnit designový systém celé společnosti, Docz, Storybook a Styleguidist jsou skvělé možnosti.
Od překladatele. Toto je moje první zkušenost s Habré. Pokud najdete nějaké nepřesnosti, nebo máte návrhy na vylepšení článku, napište mi do osobní zprávy.
Zdroj: www.habr.com