Puteți avea cel mai bun proiect open source, dar dacă nu are o documentație bună, sunt șanse să nu descopere niciodată. La birou, o documentare bună vă va împiedica să răspundeți la aceleași întrebări. Documentația asigură, de asemenea, că oamenii pot înțelege proiectul dacă angajații cheie părăsesc compania sau rolurile se schimbă. Orientările vii vor ajuta la asigurarea integrității datelor.
Dacă trebuie să scrieți text lung, Markdown este o alternativă excelentă la HTML. Uneori, sintaxa Markdown nu este suficientă. În acest caz, putem folosi HTML în interiorul acestuia. De exemplu, elemente personalizate. Prin urmare, dacă construiți un sistem de proiectare cu componente web native, acestea pot fi incluse cu ușurință în documentația text. Dacă utilizați React (sau orice alt cadru JSX precum Preact sau Vue), puteți face același lucru folosind MDX.
Acest articol este o prezentare generală a instrumentelor pentru scrierea documentației și crearea de ghiduri. Nu toate instrumentele enumerate aici folosesc MDX, dar este din ce în ce mai mult inclus în instrumentele de documentare.
Ce este MDX?
fișier .mdx are aceeași sintaxă ca Markdown, dar vă permite să importați componente JSX interactive și să le încorporați în conținutul dvs. Suportul pentru componentele Vue este în alfa. Pentru a începe să lucrați cu MDX, trebuie doar să instalați „Create React App”. Există pluginuri pentru Next.js și Gatsby. Următoarea versiune de Docusaurus (versiunea 2) va avea și suport nativ.
Scrierea documentației cu Docusaurus
Docusaurus a scris pe Facebook. Îl folosesc pentru fiecare proiect open source, cu excepția React. În afara companiei este folosit de Redux, Prettier, Gulp și Babel.
Proiecte care folosesc Docusaurus.
Docusaurus poate fi folosit pentru a scrie orice documentație, nu numai pentru a descrie interfața. Are React sub capotă, dar nu trebuie să fii familiarizat cu el pentru a-l folosi. Este nevoie de fișierele dvs. Markdown, un vârf de magie și o documentație bine structurată, formatată și lizibilă, cu un design frumos, este gata.
Pe site-ul web Redux puteți vedea șablonul standard Docusaurus
Site-urile web create cu Docusaurus pot include, de asemenea, un blog bazat pe Markdown. Prism.js este conectat imediat pentru evidențierea sintaxei. În ciuda faptului că Docusaurus a apărut relativ recent, a fost recunoscut drept cel mai bun instrument al anului 2018 pe StackShare.
Alte opțiuni de creare de conținut
Docusaurus este conceput special pentru crearea documentației. Desigur, există un milion și una de modalități de a crea un site web - puteți implementa propria soluție în orice limbă, CMS sau puteți utiliza un generator de site static.
De exemplu, documentația pentru React, sistemul de proiectare IBM, Apollo și Ghost CMS utilizează Gatsby - un generator de site static care este adesea folosit pentru bloguri. Dacă lucrați cu Vue, atunci VuePress este o opțiune bună pentru dvs. O altă opțiune este să folosiți un generator scris în Python - MkDocs. Este open source și configurat folosind un singur fișier YAML. GitBook este, de asemenea, o opțiune bună, dar este gratuit doar pentru echipele publice și non-comerciale. De asemenea, puteți să încărcați pur și simplu fișiere mardown folosind Git și să lucrați cu ele în Github.
Componente de documentare: Docz, Storybook și Styleguidist
Linii directoare, design de sistem, biblioteci de componente - indiferent cum le-ați numi, a devenit foarte popular în ultima vreme. Apariția cadrelor componente precum React și instrumentele menționate aici le-au transformat din proiecte vanitare în instrumente utile.
Storybook, Docz și Styleguidist fac toate același lucru: afișează elemente interactive și documentează API-ul lor. Un proiect poate avea zeci sau chiar sute de componente - toate cu stări și stiluri diferite. Dacă doriți ca componentele să fie reutilizate, oamenii trebuie să știe că există. Pentru a face acest lucru, pur și simplu catalogați componentele. Orientările oferă o imagine de ansamblu ușor de găsit asupra tuturor componentelor dumneavoastră. Acest lucru ajută la menținerea consistenței vizuale și la evitarea muncii repetitive.
Aceste instrumente oferă o modalitate convenabilă de a vizualiza diferite stări. Poate fi dificil să reproduci fiecare stare a unei componente în contextul unei aplicații reale. În loc să faceți clic pe aplicația reală, merită să dezvoltați o componentă separată. Stările greu accesibile (cum ar fi stările de încărcare) pot fi simulate.
Împreună cu o demonstrație vizuală a diferitelor stări și o listă de proprietăți, este adesea necesar să scrieți o descriere generală a conținutului - rațiuni de proiectare, cazuri de utilizare sau descrieri ale rezultatelor testării utilizatorilor. Markdown este foarte ușor de învățat - în mod ideal, liniile directoare ar trebui să fie o resursă comună pentru designeri și dezvoltatori. Docz, Styleguidist și Storybook oferă o modalitate de a combina cu ușurință Markdown cu componente.
Docz
În prezent, Docz funcționează numai cu React, dar se lucrează activ pentru a susține Preact, Vue și componentele web. Docz este cel mai recent dintre cele trei instrumente, dar a reușit să adune peste 14 de stele pe Github. Docz introduce două componente − <Playground> и < Props >. Sunt importate și utilizate în fișiere .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Puteți împacheta propriile componente React cu <Playground>pentru a crea un analog al CodePen sau CodeSandbox încorporat - adică vă vedeți componenta și o puteți edita.
<Playground>
<Button>click</Button>
</Playground><Props> va afișa toate proprietățile disponibile pentru o anumită componentă React, valorile implicite și dacă proprietatea este necesară.
<Props of={Button} />Personal, consider că această abordare bazată pe MDX este cea mai ușor de înțeles și cel mai ușor de lucrat.
Dacă sunteți un fan al generatorului de site-uri static Gatsby, Docz oferă o integrare excelentă.
Ghid stilistic
La fel ca Docz, exemplele sunt scrise folosind sintaxa Markdown. Styleguidist folosește blocuri de cod Markdown (ghilimele triple) în fișierele obișnuite .md fișiere, nu MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Blocurile de cod din Markdown arată de obicei doar cod. Când utilizați Styleguidist, orice bloc de cod cu o etichetă de limbă js, jsx sau javascript va reda ca o componentă React. La fel ca Docz, codul este editabil - puteți schimba proprietățile și puteți vedea instantaneu rezultatul.
Styleguidist va crea automat un tabel de proprietăți din declarații PropTypes, Flow sau Typescript.
Styleguidist acceptă în prezent React și Vue.
Carte de povești
Storybook se poziționează ca un „mediu de dezvoltare a componentelor UI”. În loc să scrieți exemple de componente în fișierele Markdown sau MDX, scrieți povestiri în interiorul fișierelor Javascript. Poveste documentează starea specifică a unei componente. De exemplu, o componentă poate avea istorice pentru o stare încărcată și o stare dezactivată (invalid).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Cartea de povești este mult mai complexă decât Styleguidist și Docz. Dar, în același timp, aceasta este cea mai populară opțiune; proiectul are peste 36 de stele pe Github. Este un proiect open source cu 000 de colaboratori și personal cu normă întreagă. Este folosit de Airbnb, Algolia, Atlassian, Lyft și Salesforce. Storybook acceptă mai multe cadre decât concurenții - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte și HTML obișnuit.
Într-o versiune viitoare vor exista funcții de la Docz și vor fi introduse MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Noile funcții ale Storybook vor fi lansate treptat în următoarele câteva luni și se pare că va fi un mare pas înainte.
Rezultatele
Beneficiile unei biblioteci de modele sunt lăudate în milioane de articole de pe Medium. Când sunt făcute bine, ele facilitează crearea de produse similare și menținerea identității. Desigur, niciunul dintre aceste instrumente nu va crea în mod magic un sistem de proiectare. Acest lucru necesită un design atent și CSS. Dar când vine timpul să facem un sistem de design accesibil întregii companii, Docz, Storybook și Styleguidist sunt opțiuni grozave.
De la traducător. Aceasta este prima mea experiență cu Habré. Dacă găsiți inexactități sau aveți sugestii pentru îmbunătățirea articolului, scrieți-mi într-un mesaj personal.
Sursa: www.habr.com