Možete imati najbolji projekt otvorenog koda, ali ako nema dobru dokumentaciju, velike su šanse da nikada neće zaživjeti. U uredu će vas dobra dokumentacija spriječiti da odgovorite na ista pitanja. Dokumentacija također osigurava da ljudi mogu razumjeti projekt ako ključni zaposlenici napuste tvrtku ili se uloge promijene. Životne smjernice pomoći će osigurati integritet podataka.
Ako trebate napisati dugačak tekst, Markdown je izvrsna alternativa HTML-u. Ponekad Markdown sintaksa nije dovoljna. U ovom slučaju unutar njega možemo koristiti HTML. Na primjer, prilagođeni elementi. Stoga, ako gradite sustav dizajna s izvornim web komponentama, one se mogu lako uključiti u tekstualnu dokumentaciju. Ako koristite React (ili bilo koji drugi JSX okvir poput Preact ili Vue), možete učiniti istu stvar s MDX-om.
Ovaj je članak široki pregled alata za pisanje dokumentacije i izradu smjernica. Ne koriste svi ovdje navedeni alati MDX, ali on se sve više uključuje u alate za dokumentaciju.
Što je MDX?
datoteka .mdx ima istu sintaksu kao Markdown, ali vam omogućuje da uvezete interaktivne JSX komponente i ugradite ih u svoj sadržaj. Podrška za Vue komponente je u alfa verziji. Za početak rada s MDX-om samo instalirajte “Create React App”. Postoje dodaci za Next.js i Gatsby. Sljedeća verzija Docusaurusa (verzija 2) također će imati izvornu podršku.
Pisanje dokumentacije s Docusaurusom
Docusaurus je napisao na Facebooku. Koriste ga na svim open source projektima osim na Reactu. Izvan tvrtke koriste ga Redux, Prettier, Gulp i Babel.
Projekti koji koriste Docusaurus.
Docusaurus se može koristiti za pisanje bilo koji dokumentaciju, ne samo za opis sučelja. Ima React ispod haube, ali ne morate biti upoznati s njim da biste ga koristili. Potrebne su vaše Markdown datoteke, prstohvat magije i dobro strukturirana, formatirana i čitljiva dokumentacija s prekrasnim dizajnom je spremna.
Na Redux web stranici možete vidjeti standardni Docusaurus predložak
Web-stranice napravljene s Docusaurusom također mogu sadržavati blog temeljen na Markdownu. Prism.js je odmah povezan za označavanje sintakse. Unatoč činjenici da se Docusaurus pojavio relativno nedavno, na StackShareu je prepoznat kao najbolji alat 2018.
Ostale mogućnosti stvaranja sadržaja
Docusaurus je posebno dizajniran za izradu dokumentacije. Naravno, postoji milijun i jedan način za izradu web stranice - možete implementirati svoje vlastito rješenje na bilo kojem jeziku, CMS-u ili koristiti generator statičnih stranica.
Primjerice, dokumentacija za React, IBM design system, Apollo i Ghost CMS koristi Gatsby – statični generator stranica koji se često koristi za blogove. Ako radite s Vueom, onda je VuePress dobra opcija za vas. Druga opcija je korištenje generatora napisanog u Pythonu - MkDocs. Otvorenog je koda i konfiguriran pomoću jedne YAML datoteke. GitBook je također dobra opcija, ali je besplatan samo za javne i nekomercijalne timove. Također možete jednostavno učitati mardown datoteke koristeći Git i raditi s njima u Githubu.
Komponente dokumentiranja: Docz, Storybook i Styleguidist
Smjernice, dizajn sustava, biblioteke komponenti - kako god ih zvali, postalo je vrlo popularno u zadnje vrijeme. Pojava sastavnih okvira poput Reacta i ovdje spomenutih alata pretvorila ih je iz ispraznih projekata u korisne alate.
Storybook, Docz i Styleguidist rade istu stvar: prikazuju interaktivne elemente i dokumentiraju svoj API. Projekt može imati desetke ili čak stotine komponenti - sve s različitim stanjima i stilovima. Ako želite da se komponente ponovno koriste, ljudi moraju znati da postoje. Da biste to učinili, jednostavno katalogizirajte komponente. Smjernice pružaju pregled svih vaših komponenti koji je lako pronaći. To pomaže u održavanju vizualne dosljednosti i izbjegavanju rada koji se ponavlja.
Ovi alati pružaju prikladan način za pregled različitih stanja. Može biti teško reproducirati svako stanje komponente u kontekstu stvarne aplikacije. Umjesto klikanja na stvarnu aplikaciju, isplati se razviti zasebnu komponentu. Teško dostupna stanja (kao što su stanja utovara) mogu se simulirati.
Uz vizualnu demonstraciju različitih stanja i popis svojstava, često je potrebno napisati opći opis sadržaja - obrazloženja dizajna, slučajeve korištenja ili opise rezultata testiranja korisnika. Markdown je vrlo lako naučiti - u idealnom slučaju, smjernice bi trebale biti zajednički resurs za dizajnere i programere. Docz, Styleguidist i Storybook nude način jednostavnog miješanja Markdowna s komponentama.
Docz
Trenutno Docz radi samo s Reactom, ali aktivno se radi na podršci za Preact, Vue i web komponente. Docz je najnoviji od tri alata, ali uspio je prikupiti preko 14 000 zvjezdica na Githubu. Docz uvodi dvije komponente − <Playground> и < Props >. Oni se uvoze i koriste u datotekama .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Možete omotati svoje vlastite React komponente <Playground>stvoriti analogiju ugrađenog CodePena ili CodeSandboxa - to jest, vidite svoju komponentu i možete je uređivati.
<Playground>
<Button>click</Button>
</Playground><Props> pokazat će sva dostupna svojstva za određenu React komponentu, zadane vrijednosti i je li svojstvo potrebno.
<Props of={Button} />Osobno smatram da je ovaj pristup temeljen na MDX-u najlakši za razumjeti i s njim najlakše raditi.
Ako ste obožavatelj generatora statičkih stranica Gatsby, Docz nudi izvrsnu integraciju.
Stilski vodič
Kao i Docz, primjeri su napisani korištenjem Markdown sintakse. Styleguidist koristi Markdown kodne blokove (trostruke navodnike) u običnim datotekama .md datoteke, a ne MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Blokovi koda u Markdownu obično samo prikazuju kod. Kada koristite Styleguidist, bilo koji blok koda s jezičnom oznakom js, jsx ili javascript prikazat će se kao React komponenta. Kao i Docz, kod je moguće uređivati - možete promijeniti svojstva i odmah vidjeti rezultat.
Styleguidist će automatski stvoriti tablicu svojstava iz PropTypes, Flow ili Typescript deklaracija.
Styleguidist trenutno podržava React i Vue.
Knjiga pripovjedaka
Storybook se pozicionira kao "okolina za razvoj komponenti korisničkog sučelja." Umjesto pisanja primjera komponenti unutar Markdown ili MDX datoteka, vi pišete povijest unutar Javascript datoteka. Priča dokumentirati specifično stanje komponente. Na primjer, komponenta može imati povijest za učitano stanje i onemogućeno stanje (onesposobljen).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook je mnogo složeniji od Styleguidista i Docza. Ali u isto vrijeme, ovo je najpopularnija opcija; projekt ima više od 36 zvjezdica na Githubu. To je projekt otvorenog koda sa 000 suradnika i stalno zaposlenih. Koriste ga Airbnb, Algolia, Atlassian, Lyft i Salesforce. Storybook podržava više okvira od konkurenata - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte i obični HTML.
U budućem izdanju bit će predstavljene značajke iz Docz-a i MDX-a.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nove značajke Storybooka uvodit će se postupno tijekom sljedećih nekoliko mjeseci i čini se da će to biti veliki korak naprijed.
Rezultati
Prednosti biblioteke uzoraka veličaju se u milijunima članaka na Mediumu. Kada su dobro izvedeni, olakšavaju stvaranje povezanih proizvoda i održavanje identiteta. Naravno, nijedan od ovih alata neće magično stvoriti sustav dizajna. To zahtijeva pažljiv dizajn i CSS. Ali kada dođe vrijeme da sustav dizajna učinite dostupnim cijeloj tvrtki, Docz, Storybook i Styleguidist izvrsne su opcije.
Od prevoditelja. Ovo je moje prvo iskustvo na Habréu. Ako pronađete netočnosti ili imate prijedloge za poboljšanje članka, pišite mi u osobnoj poruci.
Izvor: www.habr.com