У вас може бути найкращий проект із відкритим вихідним кодом, але якщо у нього немає хорошої документації, є ймовірність, що він ніколи не злетить. В офісі хороша документація дозволить вам не відповідати на ті самі питання. Документація також гарантує, що люди можуть розібратися у проекті, якщо компанію залишать ключові співробітники або зміниться ролі. Живі гайдлайни допоможуть забезпечити цілісність даних.
Якщо вам потрібно написати довгий текст, 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