Možete imati najbolji projekat sa otvorenim kodom, ali ako nema dobre dokumentacije, postoji rizik da nikada ne uspe. U kancelariji, dobra dokumentacija omogućava vam da ne odgovarate na ista pitanja iznova. Dokumentacija takođe garantuje da ljudi mogu razumeti projekat, čak i ako ključni zaposleni napuste kompaniju ili se uloge promene. Živi vodiči pomažu da se osigura integritet podataka.
Ako morate da napišete duži tekst, Markdown je odlična alternativa HTML-u. Ponekad Markdown sintaksa nije dovoljna. U tom slučaju možemo koristiti HTML unutar njega. Na primer, prilagođeni elementi. Tako da, ako gradite dizajn sistem sa nativnim web komponentama, lako ih je uključiti u tekstualnu dokumentaciju. Ako koristite React (ili bilo koji drugi JSX okvir, poput Preact ili Vue), možete učiniti isto pomoću MDX-a.
Ovaj članak je širok pregled alata za pisanje dokumentacije i izradu vodiča. Nisu svi alati navedeni ovde koristili MDX, ali se sve više uključuje u alate za dokumentovanje.
Šta je MDX?
unutar svakog kontejnera prema zadanim postavkama će izgledati ovako: .mdx ima istu sintaksu kao Markdown, ali omogućava uvoz interaktivnih JSX komponenti i njihovo ugrađivanje u vaš sadržaj. Podrška za Vue komponente je u alfa fazi. Da biste počeli da radite sa MDX, dovoljno je instalirati „Create React App“. Postoje dodaci za Next.js i Gatsby. Sledeća verzija Docusaurusa (verzija 2) će takođe imati ugrađenu podršku.
Pisanje dokumentacije sa Docusaurusom
Docusaurus je razvijen u Facebooku. Koriste ga u svakom projektu sa otvorenim kodom, osim u Reactu. Van kompanije ga koriste Redux, Prettier, Gulp i Babel.
Projekti koji koriste Docusaurus.
Docusaurus se može koristiti za pisanje katerikoli dokumentacije, ne samo za opis frontenda. Ispod haube se nalazi React, ali nije potrebno biti upoznat s njim da biste ga koristili. Uzimajući vaše Markdown fajlove, uz malu dozu magije, dobro strukturirana, formatirana i čitka dokumentacija sa lepim dizajnom je spremna.
Na sajtu Redux možete videti standardni šablon Docusaurus.
Spletne strani, ustvarjene z Docusaurusom, lahko vključujejo tudi blog, ki temelji na Markdownu. Za poudarjanje sintakse je takoj povezan Prism.js. Čeprav se je Docusaurus pojavila razmeroma nedavno, so ga na StackShareu priznali za najboljše orodje leta 2018.
Druge možnosti za ustvarjanje vsebine
Docusaurus je posebej zasnovan za izdelavo dokumentacije. Seveda obstaja milijon in en način za izdelavo spletne strani — lahko zgradite svojo rešitev v katerem koli jeziku, CMS-ju ali uporabite generator statičnih spletnih strani.
Na primer, dokumentacija za React, oblikovna sistema IBM, Apollo in Ghost CMS uporabljajo Gatsby — to je generator statičnih spletnih strani, ki se pogosto uporablja za bloge. Če delate z Vue, bo VuePress dobra izbira za vas. Druga možnost je uporaba generatorja, napisanega v Pythonu — MkDocs. Ta je odprtokoden in ga konfigurirate s pomočjo enega YAML datoteke. GitBook je prav tako dobra izbira, a je brezplačen le za odprte in nekomercialne ekipe. Lahko tudi preprosto naložite markdown datoteke, uporabite git in z njimi delate na Githubu.
Dokumentiranje komponent: Docz, Storybook in Styleguidist
Smernice, oblikovne sisteme, knjižnice komponent — kako koli jih poimenujete, so v zadnjem času postale zelo priljubljene. Pojav komponentnih okvirjev, kot je React, in tu omenjenih orodij — je omogočil, da so se spremenili iz praznovalnih projektov v koristna orodja.
Storybook, Docz in Styleguidist — delujejo na enak način: prikazujejo interaktivne elemente in dokumentirajo njihovo API. Projekt ima lahko na desetine ali celo stotine komponent — vse z različnimi stanji in slogi. Če želite, da se komponente ponovno uporabljajo, morajo ljudje vedeti, da obstajajo. Za to je dovolj, da katalogizirate komponente. Smernice ponujajo enostaven pregled vseh vaših komponent, kar pomaga pri ohranjanju vizualne doslednosti in izogibanju ponovnemu delu.
Ta orodja ponujajo enostaven način za ogled različnih stanj. Morda je težko reproducirati vsako stanje komponente v kontekstu prave aplikacije. Namesto da bi klikali po pravi aplikaciji, je bolje razviti ločeno komponento. Lahko modelirate težko dostopna stanja (na primer stanje nalaganja).
Poleg vizualne predstavitve različnih stanj in seznama lastnosti je pogosto potrebno napisati splošni opis vsebine - utemeljitev za oblikovanje, primere uporabe ali opis rezultatov uporabniškega testiranja. Markdown je zelo enostaven za učenje - idealno bi morali biti smernice skupni vir za oblikovalce in razvijalce. Docz, Styleguidist in Storybook ponujajo način enostavnega mešanja Markdowna s komponentami.
Docz
Trenutno Docz deluje samo z Reactom, vendar so v teku intenzivna dela za podporo Preactu, Vueu in spletnim komponentam. Docz je najnovejši od treh orodij, a je na Githubu uspel zbrati več kot 14.000 zvezdic. Docz predstavlja dve komponenti - <Playground> in < Props >. Importe in se uporabljajo v datotekah .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## You can _write_ **markdown**
### You can import and use components
Lahko ovijete svoje lastne React komponente s pomočjo <Playground>, da ustvarite analog vgrajenega CodePen ali CodeSandbox - to pomeni, da vidite svojo komponento in jo lahko urejate.
<Props> bo prikazal vse razpoložljive lastnosti za to React komponento, privzete vrednosti in ali je lastnost obvezna.
<Props of={Button} />Osebno menim, da je ta pristop na osnovi MDX najpreprostejši za razumevanje in najlažji za delo.
Če ste oboževalec generatorja statičnih spletnih strani Gatsby, Docz ponuja odlično integracijo.
Styleguidist
Tako kot pri Docz so primeri napisani z uporabo sintakse Markdown. Styleguidist uporablja blok kode Markdown (triple navednice) v navadnih datotekah .md datotekah, namesto v MDX.
```js
Bloki kode v Markdown običajno samo prikažejo kodo. Pri uporabi Styleguidista bo vsak blok kode z oznako jezika js, jsx ili javascript prikazan kot React komponenta. Tako kot pri Docz je koda urejevalna - lahko spremenite lastnosti in takoj vidite rezultat.
Styleguidist bo samodejno ustvaril tabelo lastnosti iz PropTypes, Flow ali Typescript izjav.
Styleguidist trenutno podpira React in Vue.
Storybook
Storybook se pozicionira kot "okolje za razvoj UI komponent". Namesto da bi pisali primere komponent znotraj datotek Markdown ali MDX, pišete zgodbe znotraj Javascript datotek. Zgodovina documentira konkretno stanje komponente. Na primjer, komponenta može imati priče za stanje učitavanja i isključeno stanje (onemogućeno).
storiesOf('Button', module)
.add('onemogućeno', () => (
))Storybook je mnogo složeniji od Styleguidist i Docz. Ipak, to je najpopularnija opcija, na Githubu projekat ima više od 36.000 zvjezdica. To je projekat s otvorenim izvorom, u njemu učestvuje 657 učesnika i podržavaju ga zaposleni. Koriste ga Airbnb, Algolia, Atlassian, Lyft i Salesforce. Storybook podržava više okvira od svojih konkurenata — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte i obični HTML.
U budućem izdanju biće funkcionalnosti iz Docz i implementira se MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nove funkcije Storybook-a biće predstavljene postepeno u narednih nekoliko meseci i, očigledno, ovo će biti veliki napredak.
Zaključki
Prednosti biblioteke obrazaca hvale se u milionima članaka na Mediumu. Kada je sve dobro urađeno, olakšavaju kreiranje povezanih proizvoda i održavanje identiteta. Naravno, nijedan od ovih alata ne može čarobno stvoriti sistem dizajna. To zahteva pažljivo projektovanje dizajna i CSS. Ali kada dođe vreme da se sistem dizajna učini dostupnim čitavoj kompaniji, Docz, Storybook i Styleguidist su odlične opcije.
Od prevodioca. Ovo je moje prvo iskustvo na Habru. Ako ste pronašli neke netačnosti ili imate sugestije za poboljšanje članka — pišite mi u privatnim porukama.
Izvor: habr.com
