У вас можа быць лепшы праект з адчыненым зыходным кодам, але калі ў яго няма добрай дакументацыі, ёсць верагоднасць, што ён ніколі не ўзляціць. У офісе добрая дакументацыя дазволіць вам не адказваць на адны і тыя ж пытанні. Дакументацыя таксама гарантуе, што людзі могуць разабрацца ў праекце, калі кампанію пакінуць ключавыя супрацоўнікі ці памяняюцца ролі. Жывыя гайдлайны дапамогуць забяспечыць цэласнасць звестак.
Калі вам трэба напісаць доўгі тэкст, Markdown - выдатная альтэрнатыва HTML. Часам сінтаксісу Markdown не дастаткова. У гэтым выпадку мы можам выкарыстоўваць HTML усярэдзіне яго. Напрыклад, кастамныя элементы. Таму калі вы будуеце дызайн-сістэму з натыўнымі вэб кампанентамі, іх лёгка ўключыць у тэкставую дакументацыю. Калі вы выкарыстоўваеце React (ці любы іншы JSX фрэймворк, напрыклад Preact ці Vue), вы можаце рабіць тое ж самае з дапамогай MDX.
Гэты артыкул - шырокі агляд інструментаў для напісання дакументацыі і стварэння гайдлайна. Не ўсе прылады, пералічаныя тут, выкарыстоўваюць MDX, але ён усё гушчару ўключаецца ў прылады дакументавання.
Што такое MDX?
файл .mdx мае той жа сінтаксіс што і Markdown, але дазваляе імпартаваць інтэрактыўныя кампаненты JSX і ўбудоўваць іх у ваш кантэнт. Падтрымка кампанентаў Vue знаходзіцца ў альфе. Для таго, каб пачаць працаваць з MDX, дастаткова ўсталяваць "Create React App". Ёсць убудовы для Next.js і Gatsby. Наступная версія Docusaurus (версія 2) таксама будзе мець убудаваную падтрымку.
Напісанне дакументацыі з Docusaurus
Docusaurus напісалі ў Facebook. Яны яго выкарыстоўваюць на кожным праекце з адчыненым зыходным кодам, акрамя React. За межамі кампаніі яго выкарыстоўвае Redux, Prettier, Gulp і Babel.
Праекты, якія выкарыстоўваюць Docusaurus.
Docusaurus можна выкарыстоўваць для напісання любы дакументацыі, не толькі для апісання франтэнда. У яго пад капотам React, але для таго, каб яго выкарыстоўваць, не абавязкова быць з ім знаёмым. Ён бярэ вашыя Markdown файлы, дробка магіі і добра структураваная, адфарматаваная і чытэльная дакументацыя з прыгожым дызайнам гатова.
На сайце Redux можна паглядзець стандарны шаблон Docusaurus
Сайты, створаныя з дапамогай Docusaurus, таксама могуць уключаць у сябе блог на аснове Markdown. Для падсвятлення сінтаксісу адразу падлучаны Prism.js. Нягледзячы на тое, што Docusaurus з'явіўся параўнальна нядаўна, яго прызналі лепшай прыладай 2018 гады на StackShare.
Іншыя варыянты стварэння кантэнту
Docusaurus спецыяльна распрацаваны для стварэння дакументацыі. Вядома, ёсць мільён і адзін спосаб зрабіць сайт - вы можаце разгарнуць сваё ўласнае рашэнне на любой мове, CMS або скарыстацца генератарам статычнага сайта.
Напрыклад, дакументацыя для React, дызайн сістэма IBM, Apollo і Ghost CMS выкарыстоўваюць Gatsby - гэта генератар статычных сайтаў, які часта выкарыстоўваюць для блогаў. Калі вы працуеце з Vue, то VuePress для вас стане добрым варыянтам. Іншы варыянт – выкарыстоўваць генератар, напісаны на Python – MkDocs. Ён адчынены і канфігуруецца з дапамогай аднаго файла YAML. GitBook таксама нядрэнны варыянт, але ён бясплатны толькі для адчыненых і некамерцыйных каманд. А яшчэ можна проста заліваць mardown файлы, выкарыстоўваючы гіт, і працаваць з імі ў Github.
Дакументаванне кампанентаў: Docz, Storybook і Styleguidist
Гайдлайны, дызайн сістэмы, бібліятэкі кампанентаў - як бы вы іх ні называлі, але гэта стала вельмі папулярным у апошні час. З'яўленне кампанентных фрэймворкаў, такіх, як React і прылад, згаданых тут - дазволіла ператварыць іх з пыхлівых праектаў у карысныя прылады.
Storybook, Docz і Styleguidist – робяць адно і тое ж: адлюстроўваюць інтэрактыўныя элементы і дакументуюць іх API. Праект можа мець дзясяткі ці нават сотні кампанентаў – усё з рознымі станамі і стылямі. Калі вы хочаце, каб кампаненты выкарыстоўваліся паўторна, людзі павінны ведаць, што яны існуюць. Для гэтага дастаткова каталагізаваць кампаненты. Гайдлайны падаюць зручны для пошуку агляд усіх вашых кампанентаў. Гэта дапамагае падтрымліваць візуальную ўзгодненасць і пазбягаць паўторнай працы.
Гэтыя прылады падаюць зручны спосаб прагляду розных станаў. Можа быць цяжка прайграць кожны стан кампанента ў кантэксце рэальнага прыкладання. Замест таго, каб пстрыкаць па рэальным дадатку, варта распрацаваць асобны кампанент. Можна змадэляваць цяжкадаступныя станы (напрыклад, стан загрузкі).
Нароўні з візуальнай дэманстрацыяй розных станаў і спісам уласцівасцяў часта неабходна пісаць агульнае апісанне кантэнту - абгрунтаванні дызайну, кейсы выкарыстання або апісанне вынікаў карыстацкага тэсціравання. Markdown вельмі просты для вывучэння - у ідэале гайдлайн павінен быць сумесным рэсурсам для дызайнераў і распрацоўшчыкаў. Docz, Styleguidist і Storybook прапануюць спосаб лёгкага змешвання Markdown з кампанентамі.
Docz
Цяпер Docz працуе толькі з React, але ідзе актыўная праца над падтрымкай Preact, Vue і вэб кампанентаў. Docz самы свежы з трох інструментаў, але на Github ён змог сабраць больш за 14 000 зорак. Docz прадстаўляе два кампаненты <Playground> и < Props >. Яны імпартуюцца і выкарыстоўваюцца ў файлах .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Вы можаце абгарнуць свае ўласныя кампаненты React з дапамогай <Playground>, Каб стварыць аналаг убудаванага CodePen або CodeSandbox - гэта значыць вы бачыце ваш кампанент і можаце яго рэдагаваць.
<Playground>
<Button>click</Button>
</Playground><Props> пакажа ўсе даступныя ўласцівасці для дадзенага кампанента React, значэнні па змаўчанні і тое, ці патрабуецца ўласцівасць.
<Props of={Button} />Асабіста я лічу гэты падыход на аснове MDX самым простым для разумення і самым простым для працы.
Калі вы фанат генератара статычных сайтаў Gatsby, Docz прапануе выдатную інтэграцыю.
Styleguidist
Як і ў Docz, прыклады пішуцца, выкарыстоўваючы сінтаксіс Markdown. Styleguidist выкарыстоўвае блокі кода Markdown (трайныя двукоссі) у звычайных файлах .md файлах, а не ў MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Блокі кода ў Markdown звычайна проста паказваюць код. Пры выкарыстанні Styleguidist любы блок кода з тэгам мовы js, jsx або javascript будзе адлюстроўвацца як кампанент React. Як і ў Docz, код рэдагуемы - вы можаце змяняць уласцівасці і імгненна бачыць вынік.
Styleguidist аўтаматычна створыць табліцу ўласцівасцяў з PropTypes, Flow ці Typescript аб'яваў.
Styleguidist зараз падтрымлівае React і Vue.
Кніга апавяданняў
Storybook пазіцыянуе сябе як "асяроддзе распрацоўкі UI кампанентаў". Замест таго, каб пісаць прыклады кампанентаў усярэдзіне файлаў Markdown або MDX, вы пішаце гісторыі усярэдзіне файлаў Javascript. Гісторыя дакументуюць пэўны стан кампанента. Напрыклад, у кампанента могуць быць гісторыі для стану загрузкі і адключанага стану (інвалід).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook значна складаней, чым Styleguidist і Docz. Але пры гэтым гэта самы папулярны варыянт, на Github у праекту больш за 36 000 зорак. Гэта праект з адчыненым зыходным кодам, у ім удзельнічае 657 удзельнікаў і суправаджаюць штатныя супрацоўнікі. Яго выкарыстоўвае Airbnb, Algolia, Atlassian, Lyft і Salesforce. Storybook падтрымлівае больш фрэймворкаў, чым канкурэнты – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte і звычайны HTML.
У будучыні рэлізе будуць фішкі з Docz і ўкараняецца MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Новы функцыі Storybook'а з'явяцца паступова на працягу наступных некалькіх месяцаў і, відаць, гэта стане вялікім крокам уперад.
Вынікі
Перавагі бібліятэкі патэрнаў узносяцца ў мільёнах артыкулаў на Medium. Калі ўсё зроблена добра, яны палягчаюць стварэнне сумежных прадуктаў і падтрыманне ідэнтычнасці. Вядома, ніводная з гэтых прылад не дапаможа чароўнай выявай стварыць дызайн сістэму. Гэта патрабуе ўважлівага праектавання дызайну і CSS. Але калі прыходзіць час зрабіць даступным дызайн сістэму для ўсёй кампаніі, Docz, Storybook і Styleguidist - выдатныя варыянты.
Ад перакладчыка. Гэта мой першы досвед на Хабры. Калі вы знайшлі нейкія не дакладнасці, ці ёсць прапановы па паляпшэнні артыкула - пішыце ў твары.
Крыніца: habr.com