Lahko imate najboljši odprtokodni projekt, a če nima dobre dokumentacije, obstaja velika verjetnost, da ne bo nikoli uspel. V pisarni vam bo dobra dokumentacija preprečila odgovarjanje na ista vprašanja. Dokumentacija tudi zagotavlja, da lahko ljudje razumejo projekt, če ključni zaposleni zapustijo podjetje ali se vloge zamenjajo. Življenjske smernice bodo pomagale zagotoviti celovitost podatkov.
Če morate napisati dolgo besedilo, je Markdown odlična alternativa HTML-ju. Včasih sintaksa Markdown ni dovolj. V tem primeru lahko znotraj njega uporabimo HTML. Na primer elementi po meri. Če torej gradite sistem oblikovanja z izvornimi spletnimi komponentami, jih je mogoče preprosto vključiti v besedilno dokumentacijo. Če uporabljate React (ali katero koli drugo ogrodje JSX, kot sta Preact ali Vue), lahko storite isto z uporabo MDX.
Ta članek je širok pregled orodij za pisanje dokumentacije in ustvarjanje smernic. Vsa orodja, našteta tukaj, ne uporabljajo MDX, vendar je vse bolj vključena v orodja za dokumentacijo.
Kaj je MDX?
datoteka .mdx ima enako sintakso kot Markdown, vendar vam omogoča uvoz interaktivnih komponent JSX in njihovo vdelavo v vašo vsebino. Podpora za komponente Vue je v različici alfa. Če želite začeti delati z MDX, samo namestite »Create React App«. Obstajajo vtičniki za Next.js in Gatsby. Naslednja različica Docusaurusa (različica 2) bo imela tudi izvorno podporo.
Pisanje dokumentacije z Docusaurusom
Docusaurus je zapisal na Facebooku. Uporabljajo ga pri vseh odprtokodnih projektih razen pri Reactu. Zunaj podjetja ga uporabljajo Redux, Prettier, Gulp in Babel.
Projekti, ki uporabljajo Docusaurus.
Docusaurus se lahko uporablja za pisanje koli dokumentacijo, ne samo za opis sprednjega dela. Pod pokrovom ima React, vendar vam ni treba, da ga poznate, da ga uporabljate. Potrebujete vaše datoteke Markdown, ščepec čarovnije in dobro strukturirana, oblikovana in berljiva dokumentacija s čudovitim dizajnom je pripravljena.
Na spletnem mestu Redux si lahko ogledate standardno predlogo Docusaurus
Spletna mesta, izdelana z Docusaurusom, lahko vključujejo tudi blog, ki temelji na Markdownu. Prism.js je takoj povezan za označevanje sintakse. Kljub dejstvu, da se je Docusaurus pojavil relativno nedavno, je bil na StackShare prepoznan kot najboljše orodje leta 2018.
Druge možnosti ustvarjanja vsebine
Docusaurus je posebej zasnovan za ustvarjanje dokumentacije. Seveda obstaja milijon in en način za izdelavo spletnega mesta – svojo lastno rešitev lahko uvedete v katerem koli jeziku, CMS ali uporabite generator statičnih spletnih mest.
Na primer, dokumentacija za React, IBM design system, Apollo in Ghost CMS uporablja Gatsby – generator statičnih spletnih mest, ki se pogosto uporablja za bloge. Če delate z Vue, potem je VuePress dobra izbira za vas. Druga možnost je uporaba generatorja, napisanega v Pythonu - MkDocs. Je odprtokoden in konfiguriran z eno samo datoteko YAML. GitBook je tudi dobra možnost, vendar je brezplačen le za javne in nekomercialne ekipe. Datoteke mardown lahko tudi preprosto naložite z uporabo Git in delate z njimi v Githubu.
Komponente dokumentiranja: Docz, Storybook in Styleguidist
Smernice, sistemska zasnova, knjižnice komponent - kakorkoli jim že rečete, je v zadnjem času postalo zelo priljubljeno. Pojav komponentnih ogrodij, kot je React, in tukaj omenjenih orodij so jih spremenili iz nečimrnih projektov v uporabna orodja.
Storybook, Docz in Styleguidist delajo isto stvar: prikazujejo interaktivne elemente in dokumentirajo svoj API. Projekt ima lahko na desetine ali celo stotine komponent – vse z različnimi stanji in slogi. Če želite, da se komponente ponovno uporabijo, morajo ljudje vedeti, da obstajajo. Če želite to narediti, preprosto katalogizirajte komponente. Smernice nudijo enostaven pregled vseh vaših komponent. To pomaga ohraniti vizualno doslednost in se izogniti ponavljajočemu se delu.
Ta orodja nudijo priročen način za ogled različnih stanj. Težko je reproducirati vsako stanje komponente v kontekstu resnične aplikacije. Namesto klikanja na dejansko aplikacijo je vredno razviti ločeno komponento. Težko dostopna stanja (kot so nakladalna stanja) je mogoče simulirati.
Poleg vizualne demonstracije različnih stanj in seznama lastnosti je pogosto treba napisati splošen opis vsebine – utemeljitve oblikovanja, primere uporabe ali opise rezultatov uporabniškega testiranja. Markdown se je zelo enostavno naučiti – v idealnem primeru bi morale biti smernice skupni vir za oblikovalce in razvijalce. Docz, Styleguidist in Storybook ponujajo način za enostavno mešanje Markdown s komponentami.
Docz
Trenutno Docz deluje samo z Reactom, vendar poteka aktivno delo za podporo Preact, Vue in spletnih komponent. Docz je najnovejše od treh orodij, vendar mu je na Githubu uspelo zbrati več kot 14 zvezdic. Docz uvaja dve komponenti − <Playground> и < Props >. Uvoženi so in uporabljeni v datotekah .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Svoje komponente React lahko ovijete z <Playground>da ustvarite analog vgrajenega CodePen ali CodeSandbox - to pomeni, da vidite svojo komponento in jo lahko urejate.
<Playground>
<Button>click</Button>
</Playground><Props> bo prikazal vse razpoložljive lastnosti za dano komponento React, privzete vrednosti in ali je lastnost obvezna.
<Props of={Button} />Osebno se mi zdi ta pristop, ki temelji na MDX, najlažji za razumevanje in z njim najlažje delati.
Če ste oboževalec generatorja statičnih spletnih mest Gatsby, Docz ponuja odlično integracijo.
Stilski vodnik
Tako kot Docz so primeri napisani s sintakso Markdown. Styleguidist uporablja bloke kode Markdown (trojne narekovaje) v običajnih datotekah .md datoteke, ne MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Bloki kode v Markdownu običajno samo prikazujejo kodo. Ko uporabljate Styleguidist, kateri koli blok kode z jezikovno oznako js, jsx ali javascript bo upodobljen kot komponenta React. Tako kot Docz je kodo mogoče urejati – spremenite lahko lastnosti in takoj vidite rezultat.
Styleguidist bo samodejno ustvaril tabelo lastnosti iz deklaracij PropTypes, Flow ali Typescript.
Styleguidist trenutno podpira React in Vue.
Zgodba
Storybook se postavlja kot »okolje za razvoj komponent uporabniškega vmesnika«. Namesto pisanja vzorčnih komponent znotraj datotek Markdown ali MDX pišete Zgodbe znotraj datotek Javascript. Zgodba dokumentira specifično stanje komponente. Na primer, komponenta ima lahko zgodovino za naloženo stanje in onemogočeno stanje (onemogočena).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook je veliko bolj zapleten kot Styleguidist in Docz. Toda hkrati je to najbolj priljubljena možnost, projekt ima več kot 36 zvezdic na Githubu. Je odprtokodni projekt s 000 sodelavci in zaposlenimi s polnim delovnim časom. Uporabljajo ga Airbnb, Algolia, Atlassian, Lyft in Salesforce. Storybook podpira več ogrodij kot konkurenti – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte in običajni HTML.
V prihodnji izdaji bodo predstavljene funkcije Docz in MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nove funkcije Storybooka bodo uvedene postopoma v naslednjih nekaj mesecih in zdi se, da bo to velik korak naprej.
Rezultati
Prednosti knjižnice vzorcev so opevane v milijonih člankov na Mediumu. Ko so dobro opravljeni, olajšajo ustvarjanje povezanih izdelkov in ohranjanje identitete. Seveda nobeno od teh orodij ne bo čarobno ustvarilo oblikovalskega sistema. To zahteva skrbno oblikovanje in CSS. Ko pa pride čas, da sistem oblikovanja naredimo dostopen celotnemu podjetju, so Docz, Storybook in Styleguidist odlične možnosti.
Od prevajalca. To je moja prva izkušnja na Habréju. Če najdete kakršne koli netočnosti ali imate predloge za izboljšavo članka, mi pišite v osebnem sporočilu.
Vir: www.habr.com