Kode irekiko proiekturik onena izan dezakezu, baina dokumentazio onik ez badu, litekeena da inoiz airea ez izatea. Bulegoan, dokumentazio onak galdera berdinei erantzutea galaraziko dizu. Dokumentazioari esker, jendeak proiektua uler dezakeela ziurtatzen du funtsezko langileek enpresa uzten badute edo rolak aldatzen badira. Bizitzeko jarraibideek datuen osotasuna ziurtatzen lagunduko dute.
Testu luzea idatzi behar baduzu, Markdown HTMLren alternatiba bikaina da. Batzuetan Markdown sintaxia ez da nahikoa. Kasu honetan HTML erabil dezakegu barruan. Adibidez, elementu pertsonalizatuak. Hori dela eta, jatorrizko web osagaiekin diseinu sistema bat eraikitzen ari bazara, erraz sar daitezke testu-dokumentazioan. React erabiltzen ari bazara (edo Preact edo Vue bezalako beste edozein JSX esparru), gauza bera egin dezakezu MDX-rekin.
Artikulu hau dokumentazioa idazteko eta jarraibideak sortzeko tresnen ikuspegi zabala da. Hemen zerrendatutako tresna guztiek ez dute MDX erabiltzen, baina gero eta gehiago sartzen da dokumentazio tresnetan.
Zer da MDX?
fitxategia .mdx Markdown-en sintaxi bera du, baina JSX osagai interaktiboak inportatzeko eta zure edukian txertatzeko aukera ematen dizu. Vue osagaien euskarria alfa-n dago. MDX-rekin lanean hasteko, instalatu besterik ez duzu "Sortu React aplikazioa". Next.js eta Gatsbyrako pluginak daude. Docusaurus-en hurrengo bertsioak (2. bertsioak) jatorrizko laguntza ere izango du.
Docusaurus-ekin dokumentazioa idaztea
Docusaurus-ek idatzi zuen Facebook-en. Iturburu irekiko proiektu guztietan erabiltzen dute React izan ezik. Enpresatik kanpo Redux, Prettier, Gulp eta Babel-ek erabiltzen dute.
Docusaurus erabiltzen duten proiektuak.
Docusaurus erabil daiteke idazteko Edozein dokumentazioa, ez bakarrik frontend-a deskribatzeko. Kanpaiaren azpian React dauka, baina ez duzu ezagutu behar hura erabiltzeko. Markdown fitxategiak hartzen ditu, magia pixka bat eta diseinu ederra duen dokumentazio ondo egituratua, formatua eta irakurgarria prest dago.
Redux webgunean Docusaurus txantiloi estandarra ikus dezakezu
Docusaurus-ekin eraikitako webguneek Markdown-en oinarritutako blog bat ere izan dezakete. Prism.js berehala konektatuta dago sintaxia nabarmentzeko. Docusaurus duela gutxi agertu zen arren, StackShare-n 2018ko tresnarik onena bezala aitortu zen.
Edukiak sortzeko beste aukera batzuk
Docusaurus dokumentazioa sortzeko bereziki diseinatuta dago. Jakina, webgune bat egiteko milioi eta bat modu daude: zure irtenbidea edozein hizkuntzatan, CMStan zabaldu dezakezu edo gune-sorgailu estatiko bat erabil dezakezu.
Adibidez, React, IBM diseinu sistema, Apollo eta Ghost CMS-ren dokumentazioak Gatsby erabiltzen du - blogetarako askotan erabiltzen den gune-sorgailu estatiko bat. Vue-rekin lan egiten baduzu, VuePress aukera ona da zuretzat. Beste aukera bat Python-en idatzitako sorgailu bat erabiltzea da - MkDocs. Kode irekikoa da eta YAML fitxategi bakarra erabiliz konfiguratuta dago. GitBook ere aukera ona da, baina doakoa da talde publiko eta komertzialez kanpokoentzat. Git erabiliz mardown fitxategiak ere igo ditzakezu eta haiekin lan egin Github-en.
Dokumentazioaren osagaiak: Docz, Storybook eta Styleguidist
Jarraibideak, sistemaren diseinua, osagaien liburutegiak - deitzen duzun edozein dela ere, azkenaldian oso ezaguna bihurtu da. React bezalako osagai-esparruen etorrerak eta hemen aipatutako tresnek hutsaltasun proiektuetatik tresna erabilgarriak bihurtu dituzte.
Storybook, Docz eta Styleguidist-ek gauza bera egiten dute: elementu interaktiboak bistaratu eta haien APIa dokumentatu. Proiektu batek dozenaka edo ehunka osagai izan ditzake, guztiak egoera eta estilo ezberdinekin. Osagaiak berrerabili nahi badituzu, jendeak jakin behar du existitzen direla. Horretarako, osagaiak katalogatu besterik ez duzu. Jarraibideek zure osagai guztien ikuspegi orokorra eskaintzen dute. Horrek koherentzia bisuala mantentzen laguntzen du eta lan errepikakorra saihesten du.
Tresna hauek egoera desberdinak ikusteko modu erosoa eskaintzen dute. Zaila izan daiteke osagai baten egoera bakoitza benetako aplikazio baten testuinguruan erreproduzitzea. Benetako aplikazioan klik egin beharrean, merezi du aparteko osagai bat garatzea. Iristeko zailak diren egoerak (adibidez, karga-egoerak) simulatu daitezke.
Hainbat egoeraren erakustaldi bisualarekin eta propietateen zerrenda batekin batera, askotan edukiaren deskribapen orokor bat idaztea beharrezkoa da: diseinuaren arrazoiak, erabilera kasuak edo erabiltzaileen proben emaitzen deskribapenak. Markdown oso erraza da ikasteko; hobe da gidalerroek diseinatzaile eta garatzaileentzako baliabide partekatu bat izan behar dutela. Docz, Styleguidist eta Storybook Markdown osagaiekin erraz nahasteko modua eskaintzen dute.
Dokz
Une honetan Docz-ek React-ekin bakarrik funtzionatzen du, baina lan aktiboa egiten ari da Preact, Vue eta web osagaiak laguntzeko. Docz da hiru tresnetatik berriena, baina 14 izar baino gehiago biltzea lortu du Github-en. Docz-ek bi osagai sartzen ditu β <Playground> ΠΈ < Props >. Fitxategietan inportatu eta erabiltzen dira .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Zure React osagaiak bil ditzakezu <Playground>integratutako CodePen edo CodeSandbox-en analogo bat sortzeko, hau da, zure osagaia ikusten duzu eta edita dezakezu.
<Playground>
<Button>click</Button>
</Playground><Props> React osagai jakin baterako erabilgarri dauden propietate guztiak, balio lehenetsiak eta propietatea beharrezkoa den erakutsiko ditu.
<Props of={Button} />Pertsonalki, MDX oinarritutako ikuspegi hau ulertzeko errazena eta lan egiteko errazena iruditzen zait.
Gatsby gune estatikoko sorgailuaren zalea bazara, Docz-ek integrazio bikaina eskaintzen du.
Estilo gida
Docz bezala, adibideak Markdown sintaxia erabiliz idazten dira. Styleguidist-ek Markdown kode blokeak (koma hirukoitzak) erabiltzen ditu fitxategi arruntetan .md fitxategiak, ez MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Markdown-en kode blokeek normalean kodea erakusten dute. Styleguidist erabiltzean, hizkuntza etiketa duen edozein kode bloke js, jsx edo javascript React osagai gisa errendatuko da. Docz-en antzera, kodea editagarria da; propietateak alda ditzakezu eta emaitza berehala ikus dezakezu.
Styleguidist-ek propietate-taula bat sortuko du automatikoki PropTypes, Flow edo Typescript adierazpenetatik.
Une honetan Styleguidist-ek React eta Vue onartzen ditu.
Ipuin liburua
Storybook "UI osagaien garapen-ingurune" gisa kokatzen da. Markdown edo MDX fitxategien barruan adibide osagaiak idatzi beharrean, idazten duzu istorioak Javascript fitxategien barruan. Story Osagai baten egoera zehatza dokumentatu. Adibidez, osagai batek kargatutako egoera baten eta desgaitutako egoera baten historiak izan ditzake (ezinduentzako).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook Styleguidist eta Docz baino askoz konplexuagoa da. Baina, aldi berean, hau da aukerarik ezagunena; proiektuak 36 izar baino gehiago ditu Github-en. Kode irekiko proiektua da, 000 laguntzaile eta lanaldi osoko langileekin. Airbnb, Algolia, Atlassian, Lyft eta Salesforce-k erabiltzen dute. Storybook-ek lehiakideek baino esparru gehiago onartzen ditu: React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte eta HTML arrunta.
Etorkizuneko bertsio batean Docz-en ezaugarriak egongo dira eta MDX sartuko da.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Storybook-en funtzio berriak pixkanaka zabalduko dira datozen hilabeteetan eta badirudi aurrerapauso handia izango dela.
Emaitzak
Eredu liburutegi baten onurak Medium-eko milioika artikulutan goraipatzen dira. Ongi egiten denean, erlazionatutako produktuak sortzea eta identitatea mantentzea errazten dute. Noski, tresna horietako batek ere ez du magiaz diseinu sistemarik sortuko. Honek diseinu zaindua eta CSS behar ditu. Baina diseinu sistema bat enpresa osoaren eskura jartzeko garaia iristen denean, Docz, Storybook eta Styleguidist aukera bikainak dira.
Itzultzailetik. Hau da HabrΓ©-n nire lehen esperientzia. Zehaztasunik aurkitzen baduzu, edo artikulua hobetzeko iradokizunik baduzu, idatzi idazu mezu pertsonal batean.
Iturria: www.habr.com