Můžete mít nejlepší projekt s otevřeným zdrojovým kódem, ale pokud nemá dobrou dokumentaci, je pravděpodobné, že nikdy neuspěje. Dobrá dokumentace v kanceláři vám umožní neodpovídat na stejné otázky znovu a znovu. Dokumentace také zajišťuje, že lidé mohou pochopit projekt, pokud klíčoví zaměstnanci odejdou nebo se změní role. Živé pokyny pomohou zajistit integritu dat.
Pokud potřebujete napsat dlouhý text, Markdown je skvělou alternativou k HTML. Někdy však syntaxe Markdown nestačí. V takovém případě můžeme uvnitř něj použít HTML. Například vlastní prvky. Pokud tedy vytváříte designový systém s nativními webovými komponenty, je snadné je zahrnout do textové dokumentace. Pokud používáte React (nebo jakýkoli jiný framework JSX, jako je Preact nebo Vue), můžete to stejné udělat pomocí 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 začleňováno do dokumentačních nástrojů.
Co je to MDX?
Soubor .mdx má stejnou syntaxi jako Markdown, ale umožňuje importovat interaktivní komponenty JSX a integrovat je do vašeho obsahu. Podpora komponent Vue je v alfa fázi. Abychom začali s MDX, stačí nainstalovat „Create React App“. Existují pluginy pro Next.js a Gatsby. Další verze Docusaurus (verze 2) také bude mít vestavěnou podporu.
Psaní dokumentace s Docusaurus
Docusaurus napsal Facebook. Používají ho u každého projektu s otevřeným zdrojovým kódem kromě Reactu. Mimo společnost jej používají Redux, Prettier, Gulp a Babel.
Projekty, které používají Docusaurus.
Docusaurus lze použít k psaní kdokoliv dokumenatce, nejen k popisu frontendu. Pod pokličkou má React, ale nemusíte být s ním obeznámení, abyste ho použili. Berou vaše Markdown soubory, s trochou magie a dobře strukturovaná, formátovaná a čitelná dokumentace s krásným designem je hotová.
Na webu Redux můžete vidět standardní šablonu Docusaurus
Webové stránky vytvořené pomocí Docusaurus mohou také zahrnovat blog založený na Markdownech. Pro zvýraznění syntaxe je hned připojen Prism.js. I když Docusaurus vznikl poměrně nedávno, byl v roce 2018 uznán jako nejlepší nástroj na StackShare.
Další možnosti pro vytváření obsahu
Docusaurus je speciálně navržen pro vytváření dokumentace. Samozřejmě existuje milion a jeden způsob, jak vytvořit web — můžete nasadit své vlastní řešení v jakémkoli jazyce, CMS, nebo použít generátor statických stránek.
Například dokumentace pro React, designový systém IBM, Apollo a Ghost CMS používají Gatsby — to je generátor statických stránek, který se často používá pro blogy. Pokud pracujete s Vue, VuePress bude pro vás dobrou volbou. Další možností je použít generátor napsaný v Pythonu — MkDocs. Je otevřený a konfiguruje se pomocí jednoho souboru YAML. GitBook je také slušná volba, ale je zdarma pouze pro otevřené a nekomerční týmy. A také lze jednoduše nahrávat markdownové soubory pomocí gitu a pracovat s nimi na GitHubu.
Dokumentace komponent: Docz, Storybook a Styleguidist
Směrnice, designové systémy, knihovny komponent — ať už je nazýváte jakkoli, staly se v poslední době velmi populárními. Vznik komponentových frameworků, jako je React a nástroje zmíněné zde — umožnily je proměnit z marnivý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 se komponenty používaly opakovaně, lidé musí vědět, že existují. K tomu stačí katalogizovat komponenty. Směrnice poskytují snadno vyhledatelný přehled všech vašich komponent. To pomáhá udržovat vizuální konzistenci a vyhnout se opakované práci.
Tyto nástroje poskytují pohodlný způsob, jak prohlížet různé stavy. Může být obtížné reprodukovat každý stav komponenty v kontextu skutečné aplikace. Místo prokliku přes skutečnou aplikaci je lepší vyvinout samostatnou komponentu. Lze modelovat obtížně přístupné stavy (například stav načítání).
Vedle vizuálního zobrazení různých stavů a seznamu vlastností je často nutné napsat obecný popis obsahu — odůvodnění designu, případy použití nebo popis výsledků uživatelského testování. Markdown je velmi snadný na naučení — ideálně by měl být průvodce společným zdrojem pro designéry a vývojáře. Docz, Styleguidist a Storybook nabízejí způsob snadného míchání Markdownu s komponenty.
Docz
Momentálně Docz pracuje pouze s React, ale probíhá aktivní vývoj podpory pro Preact, Vue a webové komponenty. Docz je nejnovější z těchto tří nástrojů, ale na Githubu získal více než 14 000 hvězdiček. Docz představuje dva komponenty — <Playground> a < Props >. Tyto komponenty se importují a používají v souborech .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Můžete _psát_ **markdown**
### Můžete importovat a používat komponenty
Můžete obalit své vlastní komponenty React pomocí <Playground>, abyste vytvořili analog vlastního CodePen nebo CodeSandbox — tedy vidíte svoji komponentu a můžete ji upravovat.
<Props> ukáže všechny dostupné vlastnosti dané komponenty React, výchozí hodnoty a zda je vlastnost povinná.
<Props of={Button} />Osobně považuji tento přístup založený na MDX za nejsrozumitelnější a nejjednodušší pro práci.
Pokud jste fanouškem generátoru statických webů Gatsby, Docz nabízí skvělou integraci.
Styleguidist
Stejně jako v Docz, příklady se píší pomocí syntaxe Markdown. Styleguidist používá bloky kódu Markdown (trojité uvozovky) v běžných souborech .md souborech, a ne v MDX.
```js
Bloky kódu v Markdown obvykle ukazují pouze kód. Při použití Styleguidist jakýkoliv blok kódu s jazykovým tagem js, jsx nebo javascript se zobrazí jako komponenta React. Podobně jako v Docz, kód je editovatelný — můžete měnit vlastnosti a okamžitě vidět výsledek.
Styleguidist automaticky vytvoří tabulku vlastností z deklarací PropTypes, Flow nebo Typescript.
Styleguidist nyní podporuje React a Vue.
Storybook
Storybook se prezentuje jako „prostředí pro vývoj UI komponent“. Místo psaní příkladů komponent uvnitř souborů Markdown nebo MDX píšete historie uvnitř souborů Javascript. Historie dokumentují konkrétní stav komponenty. Například komponenta může mít příběhy pro stav načítání a vypnutý stav (zakázáno).
storiesOf('Button', module)
.add('zakázáno', () => (
))Storybook je mnohem složitější než Styleguidist a Docz. Přesto je to nejpopulárnější volba, na GitHubu má projekt více než 36 000 hvězd. Je to projekt s otevřeným zdrojovým kódem, na kterém se podílí 657 účastníků a mají ho na starosti zaměstnanci. Používá ho Airbnb, Algolia, Atlassian, Lyft a Salesforce. Storybook podporuje více rámců než konkurenti — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte a obyčejný HTML.
V příštím vydání budou funkce z Docz a implementuje se MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nové funkce Storybooku se budou postupně objevovat v průběhu následujících několika měsíců a zřejmě to bude velký krok vpřed.
Závěry
Výhody knihovny vzorů jsou oslavovány v milionech článků na Medium. Když je všechno uděláno dobře, usnadňují vytváření souvisejících produktů a udržování identity. Samozřejmě, žádný z těchto nástrojů nemůže kouzelně vytvořit designový systém. To vyžaduje pečlivé navrhování designu a CSS. Ale když přijde čas učinit designový systém dostupným pro celou společnost, Docz, Storybook a Styleguidist jsou skvělé volby.
Od překladatele. Toto je moje první zkušenost na Habr. Pokud jste našli nějaké nepřesnosti nebo máte návrhy na zlepšení článku — pište do soukromé zprávy.
Zdroj: habr.com
