Сізде ашық бастапқы жоба жақсырақ болуы мүмкін, бірақ оның жақсы құжаттамасы болмаса, ол ешқашан іске аспауы мүмкін. Кеңседе жақсы құжаттама сізді бір сұрақтарға қайта-қайта жауап беруден сақтайды. Құжаттама сонымен қатар негізгі қызметкерлер компаниядан кетсе немесе рөлдер өзгерсе, адамдардың жобаны түсінуіне кепілдік береді. Тікелей нұсқаулар деректер тұтастығын қамтамасыз етуге көмектеседі.
Ұзын мәтін жазу қажет болса, Markdown HTML-ге тамаша балама болып табылады. Кейде Markdown синтаксисі жеткіліксіз. Бұл жағдайда оның ішінде HTML пайдалана аламыз. Мысалы, реттелетін элементтер. Сондықтан, егер сіз түпнұсқа веб-компоненттері бар дизайн жүйесін құрсаңыз, оларды мәтіндік құжаттамаға қосу оңай. Егер сіз React (немесе Preact немесе Vue сияқты кез келген басқа JSX құрылымы) қолдансаңыз, MDX-пен де солай істеуге болады.
Бұл мақала құжаттаманы жазуға және нұсқаулықты жасауға арналған құралдардың кең шолуы. Мұнда тізімделген құралдардың барлығы MDX қолданбайды, бірақ ол құжаттама құралдарына көбірек қосылып келеді.
MDX дегеніміз не?
файл .mdx Markdown сияқты синтаксиске ие, бірақ интерактивті JSX құрамдастарын импорттауға және оларды мазмұнға ендіруге мүмкіндік береді. Vue компоненттерін қолдау альфада. MDX-пен жұмыс істеуді бастау үшін «React қолданбасын жасау» орнатыңыз. Next.js және Gatsby үшін плагиндер бар. Docusaurus бағдарламасының келесі нұсқасында (2-нұсқа) кірістірілген қолдау болады.
Docusaurus көмегімен құжаттама жазу
Docusaurus Facebook желісінде жазды. Олар оны React-тен басқа кез келген ашық бастапқы жобада пайдаланады. Компаниядан тыс Redux, Prettier, Gulp және Babel оны пайдаланады.
Docusaurus пайдаланатын жобалар.
Докузаврды жазу үшін пайдалануға болады кез келген құжаттама, фронтенді сипаттау үшін ғана емес. Оның астында React бар, бірақ оны пайдалану үшін оны білудің қажеті жоқ. Ол сіздің Markdown файлдарыңызды алады, бір шымшым сиқырлы және жақсы құрылымдалған, пішімделген және әдемі дизайнымен оқылатын құжаттама дайын.
Redux веб-сайтында әдепкі Docusaurus үлгісін көре аласыз.
Docusaurus көмегімен жасалған сайттар Markdown негізіндегі блогты да қамтуы мүмкін. Синтаксисті бөлектеу үшін Prism.js бірден қосылады. Docusaurus салыстырмалы түрде жақында пайда болғанына қарамастан, ол StackShare сайтында 2018 жылдың ең жақсы құралы деп танылды.
Басқа мазмұн жасау опциялары
Docusaurus құжаттама жасау үшін арнайы жасалған. Әрине, веб-сайт жасаудың миллиондаған жолы бар - сіз өзіңіздің шешіміңізді кез келген тілде, CMS-де қолдана аласыз немесе статикалық сайт генераторын пайдалана аласыз.
Мысалы, React құжаттамасы, IBM дизайн жүйесі, Apollo және Ghost CMS блогтар үшін жиі пайдаланылатын статикалық сайт генераторы Gatsby пайдаланады. Егер сіз Vue-мен жұмыс істеп жатсаңыз, VuePress сіз үшін жақсы нұсқа. Тағы бір нұсқа - Python - MkDocs тілінде жазылған генераторды пайдалану. Ол бір YAML файлымен ашық және конфигурацияланған. GitBook - бұл жақсы нұсқа, бірақ ол тек ашық және коммерциялық емес командалар үшін тегін. Сондай-ақ git арқылы mardown файлдарын жүктеп салуға және олармен Github-та жұмыс істеуге болады.
Құрамдас құжаттама: Docz, Storybook және Styleguidist
Нұсқаулар, жүйелік дизайн, құрамдас кітапханалар, оларды қалай атағыңыз келсе де, соңғы кездері өте танымал болды. React және осы жерде айтылған құралдар сияқты құрамдас құрылымдардың пайда болуы оларды бос жобалардан пайдалы құралдарға айналдыруға мүмкіндік берді.
Storybook, Docz және Styleguidist бірдей әрекетті жасайды: интерактивті элементтерді көрсету және олардың API құжаттамасын жасау. Жобада ондаған, тіпті жүздеген құрамдас бөліктер болуы мүмкін, олардың барлығының күйлері мен стильдері әртүрлі. Құрамдастардың қайта пайдаланылуын қаласаңыз, адамдар олардың бар екенін білуі керек. Ол үшін компоненттерді каталогтау жеткілікті. Нұсқаулар барлық құрамдас бөліктеріңіздің іздеуге оңай шолуын қамтамасыз етеді. Бұл көрнекі үйлесімділікті сақтауға және қайталанатын жұмысты болдырмауға көмектеседі.
Бұл құралдар әртүрлі күйлерді көрудің ыңғайлы жолын қамтамасыз етеді. Нақты қолданба контекстінде құрамдастың әрбір күйін қайталау қиын болуы мүмкін. Нақты қолданбаны нұқудың орнына, бөлек құрамдас әзірлеу керек. Қол жеткізу қиын күйлерді модельдеуге болады (мысалы, жүктелу күйі).
Әртүрлі күйлердің көрнекі көрсетілімімен және қасиеттер тізімімен қатар, көбінесе мазмұнның жалпы сипаттамасын жазу қажет - дизайн негіздеулері, пайдалану жағдайлары немесе пайдаланушыларды тестілеу нәтижелерінің сипаттамасы. Markdown үйрену өте оңай - ең дұрысы, нұсқаулар дизайнерлер мен әзірлеушілер үшін ортақ ресурс болуы керек. Docz, Styleguidist және Storybook Markdown-ды компоненттермен оңай араластырудың жолын ұсынады.
Док
Қазіргі уақытта 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 негізіндегі тәсілді түсінуге оңай және онымен жұмыс істеу ең оңай деп санаймын.
Егер сіз Гэтсбидің статикалық сайт генераторының жанкүйері болсаңыз, Docz тамаша интеграцияларды ұсынады.
стиль жетекшісі
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 тамаша нұсқалар болып табылады.
Аудармашыдан. Бұл менің Хабредегі алғашқы тәжірибем. Егер сіз қандай да бір дәлсіздіктерді тапсаңыз немесе мақаланы жақсарту бойынша ұсыныстарыңыз болса - жекеге жазыңыз.
Ақпарат көзі: www.habr.com