Vi povas havi la plej bonan malfermfontan projekton, sed se ĝi ne havas bonan dokumentadon, verŝajne ĝi neniam ekflugos. En la oficejo, bona dokumentado malhelpos vin respondi la samajn demandojn. Dokumentado ankaŭ certigas, ke homoj povas kompreni la projekton se ŝlosilaj dungitoj forlasas la firmaon aŭ rolojn ŝanĝiĝas. Vivantaj gvidlinioj helpos certigi datuman integrecon.
Se vi bezonas skribi longan tekston, Markdown estas bonega alternativo al HTML. Kelkfoje Markdown-sintakso ne sufiĉas. En ĉi tiu kazo ni povas uzi HTML ene de ĝi. Ekzemple, kutimaj elementoj. Sekve, se vi konstruas dezajnsistemon kun denaskaj retaj komponantoj, ili povas esti facile inkluzivitaj en teksta dokumentado. Se vi uzas React (aŭ ajnan alian JSX-kadron kiel Preact aŭ Vue), vi povas fari la samon kun MDX.
Ĉi tiu artikolo estas ampleksa superrigardo de iloj por verki dokumentadon kaj krei gvidliniojn. Ne ĉiuj iloj listigitaj ĉi tie uzas MDX, sed ĝi estas pli kaj pli inkluzivita en dokumentaj iloj.
Kio estas MDX?
dosiero .mdx havas la saman sintakson kiel Markdown, sed permesas vin importi interagajn JSX-komponentojn kaj enigi ilin en via enhavo. Subteno por Vue-komponentoj estas en alfa. Por komenci labori kun MDX, simple instalu "Krei React App". Estas kromaĵoj por Next.js kaj Gatsby. La sekva versio de Docusaurus (versio 2) ankaŭ havos denaskan subtenon.
Verkado de dokumentado kun Docusaurus
Docusaurus skribis en Fejsbuko. Ili uzas ĝin en ĉiu malfermfonta projekto krom React. Ekster la firmao ĝi estas uzata de Redux, Prettier, Gulp kaj Babel.
Projektoj kiuj uzas Docusaurus.
Docusaurus povas esti uzata por skribi iu ajn dokumentado, ne nur por priskribi la fasadon. Ĝi havas React sub la kapuĉo, sed vi ne bezonas koni ĝin por uzi ĝin. Ĝi prenas viajn Markdown-dosierojn, pinĉon da magio kaj bone strukturita, formatita kaj legebla dokumentaro kun bela dezajno estas preta.
En la retejo Redux vi povas vidi la norman ŝablonon Docusaurus
Retejoj konstruitaj kun Docusaurus ankaŭ povas inkluzivi Markdown-bazitan blogon. Prism.js estas tuj konektita por sintaksa reliefigo. Malgraŭ la fakto, ke Docusaurus aperis relative lastatempe, ĝi estis rekonita kiel la plej bona ilo de 2018 ĉe StackShare.
Aliaj Enhavaj Kreaj Opcioj
Docusaurus estas specife desegnita por krei dokumentadon. Kompreneble, ekzistas miliono kaj unu manieroj fari retejon - vi povas disfaldi vian propran solvon en iu ajn lingvo, CMS, aŭ uzi statikan retejan generatoron.
Ekzemple, dokumentado por React, IBM-dezajnosistemo, Apollo kaj Ghost CMS uzas Gatsby - senmovan retejgeneratoron kiu estas ofte uzata por blogoj. Se vi laboras kun Vue, tiam VuePress estas bona elekto por vi. Alia opcio estas uzi generatoron skribitan en Python - MkDocs. Ĝi estas malferma fonto kaj agordita uzante ununuran YAML-dosieron. GitBook ankaŭ estas bona elekto, sed ĝi estas nur senpaga por publikaj kaj nekomercaj teamoj. Vi ankaŭ povas simple alŝuti mardown dosierojn uzante Git kaj labori kun ili en Github.
Dokumentaj komponantoj: Docz, Storybook kaj Styleguidist
Gvidlinioj, sistemdezajno, komponentbibliotekoj - kiel ajn vi nomas ilin, ĝi fariĝis tre populara lastatempe. La apero de komponaj kadroj kiel React kaj la iloj menciitaj ĉi tie transformis ilin de vantaj projektoj en utilajn ilojn.
Storybook, Docz kaj Styleguidist ĉiuj faras la samon: montri interagajn elementojn kaj dokumenti sian API. Projekto povas havi dekojn aŭ eĉ centojn da komponantoj - ĉiuj kun malsamaj statoj kaj stiloj. Se vi volas ke komponantoj estu reuzataj, homoj devas scii, ke ili ekzistas. Por fari tion, simple katalogu la komponantojn. Gvidlinioj provizas facile troveblan superrigardon de ĉiuj viaj komponantoj. Ĉi tio helpas konservi vidan konsistencon kaj eviti ripetan laboron.
Ĉi tiuj iloj provizas oportunan manieron por vidi malsamajn statojn. Povas esti malfacile reprodukti ĉiun staton de komponento en la kunteksto de reala aplikaĵo. Anstataŭ klaki sur la reala aplikaĵo, indas evoluigi apartan komponanton. Malfacile atingeblaj ŝtatoj (kiel ekzemple ŝarĝaj ŝtatoj) povas esti simulitaj.
Kune kun vida pruvo de diversaj statoj kaj listo de propraĵoj, estas ofte necese verki ĝeneralan priskribon de la enhavo - dezajnaj racioj, uzkazoj aŭ priskriboj de uzanttestrezultoj. Markdown estas tre facile lernebla - ideale, gvidlinioj devus esti komuna rimedo por dizajnistoj kaj programistoj. Docz, Styleguidist kaj Storybook proponas manieron facile miksi Markdown kun komponantoj.
Docz
Nuntempe Docz funkcias nur kun React, sed aktiva laboro okazas por subteni Preact, Vue kaj retajn komponantojn. Docz estas la plej lastatempa el la tri iloj, sed ĝi sukcesis kolekti pli ol 14 stelojn sur Github. Docz enkondukas du komponantojn − <Playground> и < Props >. Ili estas importitaj kaj uzataj en dosieroj .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Vi povas envolvi viajn proprajn React-komponentojn per <Playground>krei analogon de la enkonstruita CodePen aŭ CodeSandbox - tio estas, vi vidas vian komponanton kaj povas redakti ĝin.
<Playground>
<Button>click</Button>
</Playground><Props> montros ĉiujn disponeblajn ecojn por donita React-komponento, defaŭltajn valorojn, kaj ĉu la posedaĵo estas postulata.
<Props of={Button} />Persone, mi trovas, ke ĉi tiu MDX-bazita aliro estas la plej facila komprenebla kaj la plej facila por labori.
Se vi estas ŝatanto de la statika reteja generatoro de Gatsby, Docz ofertas bonegan integriĝon.
Stila gvidilo
Kiel Docz, ekzemploj estas skribitaj uzante Markdown-sintakso. Styleguidist uzas Markdown-kodblokojn (trioblaj citiloj) en regulaj dosieroj .md dosierojn, ne MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Kodblokoj en Markdown kutime nur montras kodon. Kiam vi uzas Styleguidist, ajna bloko de kodo kun lingvo-etikedo js, jsx aŭ javascript bildigos kiel React-komponento. Kiel Docz, la kodo estas redaktebla - vi povas ŝanĝi ecojn kaj tuj vidi la rezulton.
Styleguidist aŭtomate kreos proprietotabelon el PropTypes, Flow aŭ Typescript deklaroj.
Styleguidist nuntempe subtenas React kaj Vue.
Rakonlibro
Storybook poziciigas sin kiel "UI-komponenta evolumedio." Anstataŭ skribi ekzemplojn de komponantoj en Markdown aŭ MDX-dosieroj, vi skribas rakontoj ene de Javascript dosieroj. История dokumenti la specifan staton de komponento. Ekzemple, komponento povus havi historiojn por ŝarĝita stato kaj malfunkciigita ŝtato (malebligita).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook estas multe pli kompleksa ol Styleguidist kaj Docz. Sed samtempe, ĉi tiu estas la plej populara opcio; la projekto havas pli ol 36 stelojn sur Github. Ĝi estas malfermkoda projekto kun 000 kontribuantoj kaj plentempa kunlaborantaro. Ĝi estas uzata de Airbnb, Algolia, Atlassian, Lyft kaj Salesforce. Storybook subtenas pli da kadroj ol konkurantoj - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte kaj regula HTML.
En estonta eldono estos funkcioj de Docz kaj MDX estos prezentita.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>La novaj funkcioj de Storybook aperos iom post iom dum la venontaj monatoj kaj ŝajnas, ke ĝi estos granda paŝo antaŭen.
Rezultoj
La avantaĝoj de ŝablono-biblioteko estas laŭdita en milionoj da artikoloj pri Medium. Se bone faritaj, ili faciligas krei rilatajn produktojn kaj konservi identecon. Kompreneble, neniu el ĉi tiuj iloj magie kreos projektan sistemon. Ĉi tio postulas zorgan dezajnon kaj CSS. Sed kiam venas tempo por fari dezajnsistemon alirebla por la tuta kompanio, Docz, Storybook kaj Styleguidist estas bonegaj elektoj.
De la tradukinto. Jen mia unua sperto pri Habré. Se vi trovas iujn erarojn, aŭ havas sugestojn por plibonigi la artikolon, skribu al mi en persona mesaĝo.
fonto: www.habr.com