Ən yaxşı açıq mənbəli layihəyə sahib ola bilərsiniz, lakin onun yaxşı sənədləri yoxdursa, o, heç vaxt işə düşməyəcək. Ofisdə yaxşı sənədlər eyni suallara cavab verməyə mane olacaq. Sənədlər həmçinin əsas işçilər şirkətdən ayrıldıqda və ya rollar dəyişdikdə insanların layihəni başa düşməsini təmin edir. Canlı təlimatlar məlumatların bütövlüyünü təmin etməyə kömək edəcək.
Əgər uzun mətn yazmaq lazımdırsa, Markdown HTML-ə əla alternativdir. Bəzən Markdown sintaksisi kifayət deyil. Bu halda onun daxilində HTML istifadə edə bilərik. Məsələn, xüsusi elementlər. Buna görə də, əgər siz yerli veb komponentləri ilə dizayn sistemi qurursanız, onlar asanlıqla mətn sənədlərinə daxil edilə bilər. Əgər siz React (və ya Preact və ya Vue kimi hər hansı digər JSX çərçivəsi) istifadə edirsinizsə, MDX-dən istifadə edərək eyni şeyi edə bilərsiniz.
Bu məqalə sənədlərin yazılması və təlimatların yaradılması üçün alətlərə geniş baxışdır. Burada sadalanan alətlərin heç də hamısı MDX-dən istifadə etmir, lakin o, getdikcə sənədləşdirmə alətlərinə daxil edilir.
MDX nədir?
Файл .mdx Markdown ilə eyni sintaksisə malikdir, lakin sizə interaktiv JSX komponentlərini idxal etməyə və onları məzmununuza daxil etməyə imkan verir. Vue komponentləri üçün dəstək alfa səviyyəsindədir. MDX ilə işləməyə başlamaq üçün sadəcə “Reaksiya Tətbiqi Yarat” proqramını quraşdırın. Next.js və Gatsby üçün plaginlər var. Docusaurus-un növbəti versiyasında (versiya 2) yerli dəstək də olacaq.
Docusaurus ilə sənədlərin yazılması
Docusaurus Facebook-da yazıb. React istisna olmaqla, hər bir açıq mənbə layihəsində istifadə edirlər. Şirkətdən kənar Redux, Prettier, Gulp və Babel tərəfindən istifadə olunur.
Docusaurus istifadə edən layihələr.
Docusaurus yazmaq üçün istifadə edilə bilər hər hansı bir sənədlər, yalnız ön tərəfi təsvir etmək üçün deyil. Başlıq altında React var, lakin ondan istifadə etmək üçün onunla tanış olmaq lazım deyil. Markdown fayllarınızı götürür, bir çimdik sehrli və yaxşı strukturlaşdırılmış, formatlanmış və oxuna bilən gözəl dizaynı olan sənədlər hazırdır.
Redux saytında standart Docusaurus şablonunu görə bilərsiniz
Docusaurus ilə qurulan vebsaytlara Markdown əsaslı bloq da daxil ola bilər. Prism.js sintaksisi vurğulamaq üçün dərhal qoşulur. Docusaurus nisbətən yaxınlarda ortaya çıxmasına baxmayaraq, StackShare-də 2018-ci ilin ən yaxşı aləti kimi tanınıb.
Digər Məzmun Yaratma Seçimləri
Docusaurus xüsusi olaraq sənədlərin yaradılması üçün nəzərdə tutulmuşdur. Əlbəttə ki, veb sayt yaratmağın bir milyon yolu var - siz öz həllinizi istənilən dildə, CMS-də yerləşdirə və ya statik sayt generatorundan istifadə edə bilərsiniz.
Məsələn, React üçün sənədlər, IBM dizayn sistemi, Apollo və Ghost CMS Gatsby-dən istifadə edir - bloqlar üçün tez-tez istifadə olunan statik sayt generatoru. Vue ilə işləyirsinizsə, VuePress sizin üçün yaxşı seçimdir. Başqa bir seçim Python - MkDocs-da yazılmış generatordan istifadə etməkdir. O, açıq mənbədir və tək YAML faylından istifadə etməklə konfiqurasiya edilmişdir. GitBook da yaxşı seçimdir, lakin o, yalnız ictimai və qeyri-kommersiya komandaları üçün pulsuzdur. Siz həmçinin Git istifadə edərək sadəcə mardown fayllarını yükləyə və Github-da onlarla işləyə bilərsiniz.
Sənədləşdirmə komponentləri: Docz, Storybook və Styleguidist
Təlimatlar, sistem dizaynı, komponent kitabxanaları - onları nə adlandırırsınızsa, son vaxtlar çox populyardır. React kimi komponent çərçivələrinin və burada qeyd olunan alətlərin yaranması onları boş layihələrdən faydalı alətlərə çevirdi.
Storybook, Docz və Styleguidist hamısı eyni şeyi edir: interaktiv elementləri göstərin və onların API-lərini sənədləşdirin. Layihənin onlarla, hətta yüzlərlə komponenti ola bilər - hamısı müxtəlif vəziyyətlərə və üslublara malikdir. Əgər komponentlərin təkrar istifadə edilməsini istəyirsinizsə, insanlar onların mövcud olduğunu bilməlidirlər. Bunu etmək üçün sadəcə komponentləri kataloqlaşdırın. Təlimatlar bütün komponentlərinizin asan tapılan icmalını təqdim edir. Bu, vizual ardıcıllığı qorumağa və təkrarlanan işlərdən qaçmağa kömək edir.
Bu alətlər müxtəlif vəziyyətlərə baxmaq üçün rahat yol təqdim edir. Həqiqi tətbiq kontekstində komponentin hər bir vəziyyətini təkrarlamaq çətin ola bilər. Həqiqi tətbiqə klikləmək əvəzinə, ayrıca bir komponent hazırlamağa dəyər. Çətin əlçatan vəziyyətlər (məsələn, yükləmə vəziyyətləri) simulyasiya edilə bilər.
Müxtəlif vəziyyətlərin vizual nümayişi və xassələrin siyahısı ilə yanaşı, çox vaxt məzmunun ümumi təsvirini - dizayn əsaslandırmalarını, istifadə hallarını və ya istifadəçi testlərinin nəticələrinin təsvirini yazmaq lazımdır. Markdown öyrənmək çox asandır - ideal olaraq təlimatlar dizaynerlər və tərtibatçılar üçün ortaq mənbə olmalıdır. Docz, Styleguidist və Storybook Markdown-u komponentlərlə asanlıqla qarışdırmaq üçün bir yol təklif edir.
Docz
Hazırda Docz yalnız React ilə işləyir, lakin Preact, Vue və veb komponentlərini dəstəkləmək üçün aktiv iş aparılır. Docz üç alətdən ən yenisidir, lakin Github-da 14-dən çox ulduz toplamağa nail olmuşdur. Docz iki komponent təqdim edir - <Playground> и < Props >. Onlar idxal olunur və fayllarda istifadə olunur .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Siz öz React komponentlərinizi əhatə edə bilərsiniz <Playground>daxili CodePen və ya CodeSandbox analoqunu yaratmaq üçün - yəni siz öz komponentinizi görürsünüz və onu redaktə edə bilərsiniz.
<Playground>
<Button>click</Button>
</Playground><Props> verilmiş React komponenti üçün bütün mövcud xassələri, standart dəyərləri və xassə tələb olunub-olunmadığını göstərəcək.
<Props of={Button} />Şəxsən mən bu MDX əsaslı yanaşmanı başa düşmək üçün ən asan və işləmək üçün ən asan hesab edirəm.
Əgər siz Gatsby statik sayt generatorunun pərəstişkarısınızsa, Docz əla inteqrasiya təklif edir.
Stil bələdçisi
Docz kimi nümunələr Markdown sintaksisi ilə yazılır. Styleguidist adi fayllarda Markdown kod bloklarından (üçlü dırnaqlar) istifadə edir .md fayllar, MDX deyil.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Markdown-da kod blokları adətən sadəcə kodu göstərir. Styleguidist-dən istifadə edərkən dil etiketi olan hər hansı kod bloku js, jsx və ya javascript Reaksiya komponenti kimi təqdim olunacaq. Docz kimi, kod redaktə edilə bilər - xassələri dəyişdirə və dərhal nəticəni görə bilərsiniz.
Styleguidist avtomatik olaraq PropTypes, Flow və ya Typescript bəyannamələrindən xassə cədvəli yaradacaq.
Styleguidist hazırda React və Vue-ni dəstəkləyir.
Hekayə kitabı
Hekayə kitabı özünü "UI komponentinin inkişaf mühiti" kimi təqdim edir. Markdown və ya MDX faylları içərisində nümunə komponentləri yazmaq əvəzinə, siz yazırsınız hekayələr Javascript faylları içərisində. Hekayə komponentin xüsusi vəziyyətini sənədləşdirin. Məsələn, komponentin yüklənmiş vəziyyət və əlil vəziyyət üçün tarixçələri ola bilər (əlil).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Hekayə kitabı Styleguidist və Docz-dan daha mürəkkəbdir. Ancaq eyni zamanda, bu ən populyar seçimdir; layihənin Github-da 36-dən çox ulduzu var. Bu, 000 iştirakçı və tam ştatlı işçi ilə açıq mənbəli layihədir. Bu, Airbnb, Algolia, Atlassian, Lyft və Salesforce tərəfindən istifadə olunur. Hekayə kitabı rəqiblərdən daha çox çərçivələri dəstəkləyir - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte və adi HTML.
Gələcək buraxılışda Docz-dan xüsusiyyətlər olacaq və MDX təqdim ediləcək.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Storybook-un yeni xüsusiyyətləri növbəti bir neçə ay ərzində tədricən istifadəyə veriləcək və görünür, bu, irəliyə doğru böyük bir addım olacaq.
Nəticələri
Nümunə kitabxanasının faydaları Medium-da milyonlarla məqalədə təriflənir. Yaxşı iş görüldükdə, əlaqəli məhsullar yaratmağı və şəxsiyyəti qorumağı asanlaşdırırlar. Əlbəttə ki, bu vasitələrin heç biri sehrli şəkildə dizayn sistemi yaratmayacaq. Bu diqqətli dizayn və CSS tələb edir. Ancaq dizayn sistemini bütün şirkət üçün əlçatan etmək vaxtı gəldikdə, Docz, Storybook və Styleguidist əla seçimdir.
Tərcüməçidən. Bu mənim Habré ilə bağlı ilk təcrübəmdir. Hər hansı bir qeyri-dəqiqlik tapsanız və ya məqaləni təkmilləşdirmək üçün təklifləriniz varsa, mənə şəxsi mesajda yazın.
Mənbə: www.habr.com