Elavad juhised - MDX ja teised raamistikud

Teie avatud lähtekoodiga projekt võib olla suurepärane, kuid kui tal puudub hea dokumentatsioon, on tõenäolisus, et ta kunagi ei õnnestu. Hea dokumentatsioon kontoris aitab vältida pidevat samu küsimusi. Samuti tagab dokumentatsioon, et inimesed saavad projektist aru, isegi kui võtmeisikud lahkuvad ettevõttest või rollid muutuvad. Elavad juhised aitavad tagada andmete järjepidevuse.

Kui peate kirjutama pika teksti, on Markdown suurepärane alternatiiv HTML-ile. Mõnikord ei piisa Markdowni süntaksist. Sellisel juhul saame kasutada HTML-i selle sees. Näiteks kohandatud elemendid. Seega, kui loote disainisüsteemi koos natiivsete veebikomponentidega, on neid lihtne oma tekstidokumentatsioonis kasutada. Kui kasutate Reacti (või mõnda muud JSX raamistikku, näiteks Preact või Vue), saate sama teha MDX abil.

See artikkel on lai ülevaade dokumentatsiooni kirjutamise ja juhendite loomiseks mõeldud tööriistadest. Mitte kõik siin loetletud tööriistad ei kasuta MDX-i, kuid see muutub üha sagedamini dokumenteerimisvahendites.

Mis on MDX?

Fail .mdx kasutab sama süntaksit nagu Markdown, kuid võimaldab importida interaktiivseid JSX-komponente ja integreerida neid teie sisusse. Vue'i komponentide tugi on veel alfa-etapis. MDX-iga töötamiseks piisab "Create React App" installimisest. Next.js ja Gatsby jaoks on olemas pluginaid. Docusaurus järgmine versioon (versioon 2) toetab samuti sisseehitatud tuge.

Dokumentatsiooni kirjutamine Docusaurusega

Docusauruse lõi Facebook. Nad kasutavad seda iga avatud lähtekoodiga projekti puhul, välja arvatud React. Väljaspool ettevõtet kasutavad seda Redux, Prettier, Gulp ja Babel.

Projektid, mis kasutavad Docusaurust.

Docusaurust saab kasutada dokumentatsiooni kirjutamiseks, mitte ainult frontendi kirjeldamiseks. Selle all on React, kuid selle kasutamiseks ei ole hädavajalik sellega tuttav olla. See võtab teie Markdown-failid, veidi maagiat ja hästi struktureeritud, vormindatud ning loetav dokumentatsioon kauni disainiga on valmis. (mõelgem kõrgesse ametisse olevatele inimestele), siis on see halb Reduxi saidilt saab vaadata Docusauruse standardset šablooni.

Reduxi veebisaidilt on võimalik näha Docusauruse standardset šablooni.

Docusaurusiga loodud saidid võivad sisaldada ka Markdownipõhist blogi. Süntaksi esiletõstmiseks on juba ühendatud Prism.js. Kuigi Docusaurus on suhteliselt uus, tunnustati seda 2018. aasta parima tööriistana StackShare'is.

Teised sisuloomise võimalused

Docusaurus on spetsiaalselt loodud dokumentatsiooni loomiseks. Loomulikult on miljon ja üks võimalus veebisaidi loomiseks — saate välja arendada oma lahenduse igasugustes keeltes, CMS-ides või kasutada staatilise saidi genereerijat.

Näiteks kasutavad Reacti dokumentatsioon, IBM-i disainisüsteem, Apollo ja Ghost CMS Gatsby't — see on staatiliste veebisaitide genereerija, mida sageli kasutatakse blogide jaoks. Kui töötate Vue'iga, on VuePress teile hea valik. Teine variant on kasutada Pythoni kirjutatud genereerijat – MkDocs. See on avatud ja konfigureeritav ühe YAML-failiga. GitBook on samuti hea variant, kuid see on tasuta vaid avatud ja mittetulunduslikele meeskondadele. Samuti saab lihtsalt laadida markdown-failid üles, kasutades git'i, ja nendega töötada GitHubis.

Komponentide dokumenteerimine: Docz, Storybook ja Styleguidist

Juhised, disainisüsteemid, komponentide raamatukogud — olenemata sellest, kuidas te neid nimetate, on need viimasel ajal muutunud väga populaarseks. Komponentide raamistike, nagu React, ja siin mainitud tööriistade ilmumine on muutnud need tühjadesse projektidesse kasulikeks tööriistadeks.

Storybook, Docz ja Styleguidist teevad kõik sama: nad kuvavad interaktiivseid elemente ja dokumenteerivad nende API-d. Projekt võib sisaldada kümneid või isegi sadu komponente — kõik erinevate olekute ja stiilidega. Kui soovite, et komponente saab uuesti kasutada, peab olema selge, et need eksisteerivad. Selleks piisab komponentide kataloogist. Juhised pakuvad mugavat ülesehitust, et näha kõiki teie komponente. See aitab säilitada visuaalset järjepidevust ja vältida korduvat tööd.

Need tööriistad pakuvad mugavat viisi erinevate olekute vaatamiseks. Iga komponendi oleku taasilmutamine reaalses rakenduse kontekstis võib olla keeruline. Selle asemel, et klõpsata reaalses rakenduses, on mõistlik välja töötada eraldi komponent. Saate mudelida raskesti ligipääsetavaid olekuid (näiteks laadimisolekut).

Koos visuaalse esituse erinevate olekute ja omaduste loetelu, on sageli vajalik kirjutada sisu üldine kirjeldus — disaini õigustus, kasutusjuhud või kasutajate testimise tulemuste kirjeldus. Markdown on väga lihtne õppida — ideaalis peaks juhend olema koostööresurss disaineritele ja arendajatele. Docz, Styleguidist ja Storybook pakuvad võimalust lihtsalt segada Markdowni komponente.

Docz

Praegu toetab Docz ainult Reacti, kuid aktiivselt töötatakse Preacti, Vue ja veebikomponentide toe kallal. Docz on kolmest tööriistast uusim, kuid on GitHubis kogunud üle 14 000 tähe. Docz esindab kahte komponenti — <Playground> ja < Props >. Need imporditakse ja kasutatakse failides .mdx.

import { Playground, Props } from "docz";
import Button from "..\/src\/Button";

## Sa võid _kirjutada_ **markdowni**
### Sa võid importida ja kasutada komponente

click

Sa saad oma React komponendid mähkida <Playground>, et luua sisseehitatud CodePen või CodeSandbox kogemusele sarnane — see tähendab, et sa näed oma komponenti ja saad seda redigeerida.

click

<Props> näitab kõiki saadaval olevaid omadusi selle React komponendi jaoks, vaikimisi väärtusi ja kas omadus on vajalik.

<Props of={Button} />

Isiklikult leian, et see MDX-põhine lähenemine on kõige arusaadavam ja lihtsaim töödelda.

Kui oled staatiliste veebilehtede generaatori Gatsby fänn, pakub Docz suurepärast integratsiooni.

Styleguidist

Nagu Doczis, kirjutatakse näidised kasutades Markdowni süntaksit. Styleguidist kasutab tavainfote failides Markdowni koodiblokke (kolm jutumärki) .md failides, mitte MDX-is.

```js
 console.log('clicked')}>Push Me

Markdowni koodiblokid näitavad tavaliselt lihtsalt koodi. Styleguidisti kasutamisel kuvab iga koodiblokk, millel on keele silt js, jsx või javascript , kui Reacti komponent. Nagu Doczis, on kood redigeeritav — sa saad omadusi muuta ja kohe tulemusi näha.

Styleguidist loob automaatselt omaduste tabeli PropTypes, Flow või Typescripti deklaratsioonidest.

Styleguidist toetab praegu Reacti ja Vue-d.

Storybook

Storybook positsioneerib end kui „UI komponentide arenduskeskkond“. Selle asemel, et kirjutada komponentide näidiseid Markdowni või MDX failides, kirjutad lood JavaScripti failides. Ajalugu dokumenteerivad konkreetset komponenti olekut. Näiteks võib komponendil olla laadimise ja välja lülitatud oleku ajalugu (välja lülitatud).

storiesOf('Button', module)
  .add('välja lülitatud', () => (
    <Button disabled>loremi ipsum<\/Button>
  ))

Storybook on palju keerulisem kui Styleguidist ja Docz. Küll aga on see kõige populaarsem valik, GitHubis on projektile üle 36 000 tähe. See on avatud lähtekoodiga projekt, kus osaleb 657 kaaslast ja toetatakse töötajate poolt. Seda kasutavad Airbnb, Algolia, Atlassian, Lyft ja Salesforce. Storybook toetab rohkem raamistikku kui konkurendid — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte ja tavaline HTML.

Järgmises versioonis on funktsioone Doczist ja MDX rakendamine.

# Button

Some _notes_ about your button written with **markdown syntax**.

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

Uued Storybooki funktsioonid ilmuvad järk-järgult järgmise paari kuu jooksul ja näib, et see on suur samm edasi.

Summary

Musterraamatute eelised on kajastatud miljonites artiklites Mediumis. Kui kõik on hästi tehtud, lihtsustavad nad seotud toodete loomist ja identiteedi säilitamist. Loomulikult ei tunne ükski neist tööriistadest maagiliselt disainisüsteemi loomiseks. See nõuab hoolikat disaini ja CSS-i kavandamist. Kuid kui tuleb aeg teha disainisüsteem kergesti kättesaadavaks kogu ettevõttele, on Docz, Storybook ja Styleguidist suurepärased valikud.

Tõlkijalt. See on minu esimene kogemus Habras. Kui leidsite mingeid ebatäpsusi või on teil ettepanekuid artikli parandamiseks — kirjutage mulle isiklikult.

Allikas: habr.com