Možete imati najbolji projekt s otvorenim kodom, ali ako nema dobre dokumentacije, postoji mogućnost da nikada ne uspe. Dobra dokumentacija u uredu omogućava vam da ne odgovarate na ista pitanja iznova. Takođe osigurava da ljudi mogu razumeti projekat ako ključni zaposleni napuste kompaniju ili se promene uloge. Žive smernice pomažu u očuvanju integriteta podataka.
Ako trebate napisati dugi 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đene elemente. Stoga, ako gradite dizajn sistem s nativnim web komponentama, lako ih je uključiti u tekstualnu dokumentaciju. Ako koristite React (ili bilo koji drugi JSX okvir, kao što su Preact ili Vue), možete učiniti isto koristeći MDX.
Ovo je članak — širok pregled alata za pisanje dokumentacije i kreiranje smernica. Nisu svi alati navedeni ovde utemeljeni na MDX-u, ali se sve više uključuju u alate za dokumentaciju.
Što je MDX?
Datoteka .mdx ima istu sintaksu kao i 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 započeli s radom s MDX-om, dovoljno je instalirati „Create React App“. Postoje dodaci za Next.js i Gatsby. Sledeća verzija Docusaurusa (verzija 2) takođe će imati ugrađenu podršku.
Pisanje dokumentacije s Docusaurus-om
Docusaurus su razvili u Facebooku. Koriste ga u svakom projektu s otvorenim kodom, osim Reacta. Osim kompanije, koristi ga Redux, Prettier, Gulp i Babel.
Projekti koji koriste Docusaurus.
Docusaurus se može koristiti za pisanje bilo koje dokumentacije, ne samo za opisivanje frontenda. U osnovi ima React, ali nije potrebno biti upoznat s njim da biste ga koristili. Uzimaju vaše Markdown datoteke, prstohvat magije i dobro strukturirana, formatirana i čitljiva dokumentacija s lepim dizajnom je spremna.
Na sajtu Redux možete videti standardni šablon Docusaurus
Web stranice stvorene pomoću Docusaurusa također mogu uključivati blog temeljen na Markdownu. Za isticanje sintakse odmah je uključen Prism.js. Iako je Docusaurus relativno nov alat, proglašen je najboljim alatom 2018. godine na StackShareu.
Ostale opcije za izradu sadržaja
Docusaurus je posebno dizajniran za izradu dokumentacije. Naravno, postoji milijun i jedan način za izradu web stranice – možete pokrenuti svoje rješenje na bilo kojem jeziku, CMS-u ili iskoristiti generator statičkih stranica.
Na primjer, dokumentacija za React, dizajnerski sustav IBM-a, Apollo i Ghost CMS koriste Gatsby – to je generator statičkih stranica koji se često koristi za blogove. Ako radite s Vue-om, VuePress će biti dobra opcija za vas. Druga opcija je koristiti generator napisan na Pythonu – MkDocs. On je otvoren i konfigurira se pomoću jednog YAML datoteke. GitBook je također dobar izbor, ali je besplatan samo za otvorene i neprofitne timove. Također, možete jednostavno učitati markdown datoteke koristeći git i raditi s njima na GitHubu.
Dokumentiranje komponenata: Docz, Storybook i Styleguidist
Smjernice, dizajnerski sustavi, biblioteke komponenti – bez obzira kako ih nazvali, postali su vrlo popularni u posljednje vrijeme. Pojava komponentnih okvira, poput React-a i alata spomenutih ovdje, omogućila je da se oni pretvore iz ispraznih projekata u korisne alate.
Storybook, Docz i Styleguidist rade isto: prikazuju interaktivne elemente i dokumentiraju njihov API. Projekt može imati desetke ili stotine komponenti – sve s različitim stanjem i stilovima. Ako želite da se komponente ponovno koriste, ljudi moraju znati da postoje. Za to je dovoljno katalogizirati komponente. Smjernice pružaju pregled svih vaših komponenti koji se lako pretražuje. To pomaže održavanju vizualne dosljednosti i izbjegavanju ponovnog rada.
Ovi alati pružaju jednostavan način za pregled različitih stanja. Može biti teško reproducirati svako stanje komponente u kontekstu stvarne aplikacije. Umjesto da se klikće po stvarnoj aplikaciji, bolje je razviti posebnu komponentu. Može se simulirati teško dostupna stanja (npr. stanje učitavanja).
Uz vizualnu demonstraciju različitih stanja i popis svojstava, često je potrebno napisati opće opisno sadržaj — opravdanje dizajna, primjere korištenja ili opis rezultata korisničkog testiranja. Markdown je vrlo jednostavan za naučiti — idealno, smjernice bi trebale biti zajednički resurs za dizajnere i programere. Docz, Styleguidist i Storybook nude način lakog miješanja Markdowna s komponentama.
Docz
Trenutno Docz radi samo s React, ali se aktivno radi na podršci za Preact, Vue i web komponente. Docz je najnoviji od ta tri alata, no na Githubu je uspio prikupiti više od 14.000 zvijezda. Docz predstavlja dvije komponente — <Playground> i < Props >. One se uvoze i koriste u datotekama .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Možete _pisati_ **markdown**
### Možete uvesti i koristiti komponente
Možete obaviti vlastite React komponente uz <Playground>, kako biste stvorili analogiju s ugrađenim CodePen ili CodeSandbox — što znači da vidite vašu komponentu i možete je uređivati.
<Props> prikazat će sve dostupne osobine za ovu React komponentu, zadane vrijednosti i da li je osobina obavezna.
<Props of={Button} />Osobno smatram da je ovaj pristup temeljen na MDX najlakše razumljiv i najjednostavniji za rad.
Ako ste obožavatelj generatora statičkih stranica Gatsby, Docz nudi odličnu integraciju.
Styleguidist
Kao i u Docz, primjeri se pišu koristeći Markdown sintaksu. Styleguidist koristi Markdown blokove koda (trostruki navodnici) u običnim datotekama .md datotekama, a ne u MDX.
```js
Blokovi koda u Markdown obično jednostavno prikazuju kod. Kada koristite Styleguidist, svaki blok koda s oznakom jezika js, jsx ili javascript bit će prikazan kao React komponenta. Kao i u Docz, kod je uređivan — možete mijenjati osobine i odmah vidjeti rezultat.
Styleguidist automatski će generirati tablicu osobina iz PropTypes, Flow ili Typescript deklaracija.
Styleguidist trenutno podržava React i Vue.
Storybook
Storybook se pozicionira kao "okruženje za razvoj UI komponenti". Umjesto da pišete primjere komponenti unutar Markdown ili MDX datoteka, pišete priče unutar JavaScript datoteka. Povijest dokumentiraju konkretno stanje komponente. Na primjer, komponenta može imati priče za stanje učitavanja i stanje isključeno (onemogućeno).
storiesOf('Button', module)
.add('onemogućeno', () => (
))Storybook je mnogo složeniji od Styleguidista i Docza. Ipak, to je najpopularnija opcija, na GitHubu projekt ima više od 36.000 zvjezdica. Ovo je projekt otvorenog koda, s 657 sudionika i podrškom zaposlenika. Koriste ga Airbnb, Algolia, Atlassian, Lyft i Salesforce. Storybook podržava više okvira nego konkurenti — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte i običan HTML.
U budućem izdanju bit će funkcije iz Docza i implementira se MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nove značajke Storybook-a bit će postepeno dostupne tijekom sljedećih nekoliko mjeseci i to će, čini se, biti veliki korak naprijed.
Zaključci
Prednosti biblioteke obrazaca hvaljene su u milijunima članaka na Mediumu. Kada su svi aspekti dobro izvedeni, olakšavaju stvaranje srodnih proizvoda i održavanje identiteta. Naravno, nijedan od ovih alata ne može čarobno stvoriti dizajnerski sustav. To zahtijeva pažljivo projektiranje dizajna i CSS-a. No, kada dođe vrijeme za omogućavanje dizajnerskog sustava za cijelu tvrtku, Docz, Storybook i Styleguidist su odlične opcije.
Od prevodioca. Ovo je moje prvo iskustvo na Hakku. Ako ste primijetili neke netočnosti ili imate prijedloge za poboljšanje članka — pišite mi u privatne poruke.
Izvor: habr.com
