Jums var bÅ«t vislabÄkais atvÄrtÄ pirmkoda projekts, taÄu, ja tam nav labas dokumentÄcijas, iespÄjams, tas nekad neizdosies. BirojÄ laba dokumentÄcija neļaus jums atbildÄt uz tiem paÅ”iem jautÄjumiem. DokumentÄcija arÄ« nodroÅ”ina, ka cilvÄki var saprast projektu, ja galvenie darbinieki pamet uzÅÄmumu vai mainÄs lomas. DzÄ«vÄs vadlÄ«nijas palÄ«dzÄs nodroÅ”inÄt datu integritÄti.
Ja nepiecieÅ”ams rakstÄ«t garu tekstu, Markdown ir lieliska alternatÄ«va HTML. Dažreiz Markdown sintakse nav pietiekama. Å ajÄ gadÄ«jumÄ mÄs tajÄ varam izmantot HTML. PiemÄram, pielÄgoti elementi. TÄpÄc, ja veidojat dizaina sistÄmu ar vietÄjiem tÄ«mekļa komponentiem, tos var viegli iekļaut teksta dokumentÄcijÄ. Ja izmantojat React (vai jebkuru citu JSX sistÄmu, piemÄram, Preact vai Vue), varat darÄ«t to paÅ”u, izmantojot MDX.
Å is raksts ir plaÅ”s pÄrskats par dokumentÄcijas rakstÄ«Å”anas un vadlÄ«niju izveides rÄ«kiem. Ne visi Å”eit uzskaitÄ«tie rÄ«ki izmanto MDX, taÄu tas arvien vairÄk tiek iekļauts dokumentÄcijas rÄ«kos.
Kas ir MDX?
fails .mdx ir tÄda pati sintakse kÄ Markdown, taÄu ļauj importÄt interaktÄ«vos JSX komponentus un iegult tos savÄ saturÄ. Atbalsts Vue komponentiem ir alfa versijÄ. Lai sÄktu darbu ar MDX, vienkÄrÅ”i instalÄjiet āCreate React Appā. Ir spraudÅi Next.js un Gatsby. NÄkamajai Docusaurus versijai (2. versijai) bÅ«s arÄ« vietÄjais atbalsts.
DokumentÄcijas rakstÄ«Å”ana ar Docusaurus
Docusaurus rakstÄ«ja Facebook. ViÅi to izmanto visos atvÄrtÄ pirmkoda projektos, izÅemot React. Ärpus uzÅÄmuma to izmanto Redux, Prettier, Gulp un Babel.
Projekti, kuros tiek izmantots Docusaurus.
Docusaurus var izmantot rakstÄ«Å”anai jebkurÅ” dokumentÄciju, ne tikai, lai aprakstÄ«tu priekÅ”galu. Tam zem pÄrsega ir React, taÄu, lai to izmantotu, jums tas nav jÄzina. Ir nepiecieÅ”ami jÅ«su Markdown faili, ŔķipsniÅa burvju un labi strukturÄta, formatÄta un lasÄma dokumentÄcija ar skaistu dizainu ir gatava.
Redux vietnÄ varat redzÄt standarta Docusaurus veidni
VietnÄs, kas izveidotas, izmantojot Docusaurus, var bÅ«t arÄ« Markdown emuÄrs. Prism.js tiek nekavÄjoties pievienots sintakses izcelÅ”anai. Neskatoties uz to, ka Docusaurus parÄdÄ«jÄs salÄ«dzinoÅ”i nesen, vietnÄ StackShare tas tika atzÄ«ts par 2018. gada labÄko rÄ«ku.
Citas satura izveides iespÄjas
Docusaurus ir Ä«paÅ”i izstrÄdÄts dokumentÄcijas veidoÅ”anai. Protams, ir miljons un viens veids, kÄ izveidot vietni ā jÅ«s varat izvietot savu risinÄjumu jebkurÄ valodÄ, CMS vai izmantot statisko vietÅu Ä£eneratoru.
PiemÄram, React, IBM dizaina sistÄmas, Apollo un Ghost CMS dokumentÄcijÄ tiek izmantots Gatsby - statisks vietÅu Ä£enerators, ko bieži izmanto emuÄriem. Ja strÄdÄjat ar Vue, VuePress jums ir labs risinÄjums. VÄl viena iespÄja ir izmantot Python rakstÄ«tu Ä£eneratoru - MkDocs. Tas ir atvÄrts avots un konfigurÄts, izmantojot vienu YAML failu. GitBook ir arÄ« laba iespÄja, taÄu tÄ ir bezmaksas tikai publiskÄm un nekomerciÄlÄm komandÄm. Varat arÄ« vienkÄrÅ”i augÅ”upielÄdÄt mardown failus, izmantojot Git, un strÄdÄt ar tiem pakalpojumÄ Github.
DokumentÄcijas komponenti: Docz, Storybook un Styleguidist
VadlÄ«nijas, sistÄmu dizains, komponentu bibliotÄkas ā lai kÄ tÄs sauktu, pÄdÄjÄ laikÄ tas ir kļuvis ļoti populÄrs. Komponentu sistÄmu, piemÄram, React, un Å”eit minÄto rÄ«ku parÄdÄ«Å”anÄs ir pÄrvÄrtusi tos no iedomÄ«bas projektiem par noderÄ«giem rÄ«kiem.
Storybook, Docz un Styleguidist dara to paÅ”u: parÄda interaktÄ«vos elementus un dokumentÄ to API. Projektam var bÅ«t desmitiem vai pat simtiem komponentu ā visiem ar dažÄdiem stÄvokļiem un stiliem. Ja vÄlaties, lai komponenti tiktu atkÄrtoti izmantoti, cilvÄkiem ir jÄzina, ka tie pastÄv. Lai to izdarÄ«tu, vienkÄrÅ”i izveidojiet komponentu katalogu. VadlÄ«nijas nodroÅ”ina viegli atrodamu visu jÅ«su komponentu pÄrskatu. Tas palÄ«dz saglabÄt vizuÄlo konsekvenci un izvairÄ«ties no atkÄrtota darba.
Å ie rÄ«ki nodroÅ”ina Ärtu veidu, kÄ skatÄ«t dažÄdus stÄvokļus. Var bÅ«t grÅ«ti reproducÄt katru komponenta stÄvokli reÄlas lietojumprogrammas kontekstÄ. TÄ vietÄ, lai noklikŔķinÄtu uz faktiskÄs lietojumprogrammas, ir vÄrts izstrÄdÄt atseviŔķu komponentu. Var simulÄt grÅ«ti sasniedzamus stÄvokļus (piemÄram, ielÄdes stÄvokļus).
ParalÄli dažÄdu stÄvokļu vizuÄlai demonstrÄÅ”anai un Ä«paŔību sarakstam bieži vien ir nepiecieÅ”ams uzrakstÄ«t vispÄrÄ«gu satura aprakstu ā dizaina pamatojumu, lietoÅ”anas gadÄ«jumus vai lietotÄju testÄÅ”anas rezultÄtu aprakstus. Markdown ir ļoti viegli iemÄcÄ«ties ā ideÄlÄ gadÄ«jumÄ vadlÄ«nijÄm vajadzÄtu bÅ«t kopÄjam resursam dizaineriem un izstrÄdÄtÄjiem. Docz, Styleguidist un Storybook piedÄvÄ veidu, kÄ viegli sajaukt Markdown ar komponentiem.
Docz
PaÅ”laik Docz strÄdÄ tikai ar React, taÄu notiek aktÄ«vs darbs, lai atbalstÄ«tu Preact, Vue un tÄ«mekļa komponentus. Docz ir jaunÄkais no trim rÄ«kiem, taÄu tam Github ir izdevies savÄkt vairÄk nekÄ 14 000 zvaigžÅu. Docz ievieÅ” divus komponentus ā <Playground> Šø < Props >. Tie tiek importÄti un izmantoti failos .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>JÅ«s varat ietÄ«t savus React komponentus ar <Playground>lai izveidotu iebÅ«vÄtÄ CodePen vai CodeSandbox analogu - tas ir, jÅ«s redzat savu komponentu un varat to rediÄ£Ät.
<Playground>
<Button>click</Button>
</Playground><Props> parÄdÄ«s visus pieejamos rekvizÄ«tus konkrÄtajam React komponentam, noklusÄjuma vÄrtÄ«bas un to, vai rekvizÄ«ts ir nepiecieÅ”ams.
<Props of={Button} />PersonÄ«gi es uzskatu, ka Ŕī uz MDX balstÄ«tÄ pieeja ir visvieglÄk saprotama un ar to visvieglÄk strÄdÄt.
Ja esat Gatsby statisko vietÅu Ä£eneratora cienÄ«tÄjs, Docz piedÄvÄ lielisku integrÄciju.
Stila rokasgrÄmata
TÄpat kÄ Docz, piemÄri tiek rakstÄ«ti, izmantojot Markdown sintaksi. Styleguidist parastajos failos izmanto Markdown koda blokus (trÄ«skÄrÅ”Äs pÄdiÅas). .md faili, nevis MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Koda bloki pakalpojumÄ Markdown parasti tikai parÄda kodu. Izmantojot Styleguidist, jebkurÅ” koda bloks ar valodas tagu js, jsx vai javascript tiks renderÄts kÄ React komponents. TÄpat kÄ Docz, kods ir rediÄ£Äjams - jÅ«s varat mainÄ«t rekvizÄ«tus un uzreiz redzÄt rezultÄtu.
Styleguidist automÄtiski izveidos rekvizÄ«tu tabulu no PropTypes, Flow vai Typescript deklarÄcijÄm.
Styleguidist paŔlaik atbalsta React un Vue.
StÄstu grÄmata
StÄstu grÄmata sevi pozicionÄ kÄ āUI komponentu izstrÄdes vidiā. TÄ vietÄ, lai rakstÄ«tu piemÄru komponentus Markdown vai MDX failos, jÅ«s rakstÄt stÄsti Javascript failos. StÄsts dokumentÄjiet komponenta Ä«paÅ”o stÄvokli. PiemÄram, komponentam var bÅ«t vÄstures ielÄdes stÄvoklim un atspÄjotam stÄvoklim (invalÄ«diem).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))StÄstu grÄmata ir daudz sarežģītÄka nekÄ Stylegudist un Docz. Bet tajÄ paÅ”Ä laikÄ Å”Ä« ir vispopulÄrÄkÄ iespÄja; projektam Github ir vairÄk nekÄ 36 000 zvaigžÅu. Tas ir atvÄrtÄ pirmkoda projekts ar 657 lÄ«dzstrÄdniekiem un pilnas slodzes darbiniekiem. To izmanto Airbnb, Algolia, Atlassian, Lyft un Salesforce. Storybook atbalsta vairÄk ietvaru nekÄ konkurenti ā React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte un parastais HTML.
NÄkamajÄ laidienÄ tiks ieviestas Docz funkcijas un tiks ieviestas MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Storybook jaunÄs funkcijas pakÄpeniski tiks ieviestas nÄkamo dažu mÄneÅ”u laikÄ, un Ŕķiet, ka tas bÅ«s liels solis uz priekÅ”u.
RezultÄti
Rakstu bibliotÄkas priekÅ”rocÄ«bas ir izceltas miljonos rakstu par Medium. Ja tas ir izdarÄ«ts labi, tie atvieglo saistÄ«tu produktu izveidi un identitÄtes saglabÄÅ”anu. Protams, neviens no Å”iem rÄ«kiem maÄ£iski neradÄ«s dizaina sistÄmu. Tas prasa rÅ«pÄ«gu dizainu un CSS. Bet, kad ir pienÄcis laiks padarÄ«t dizaina sistÄmu pieejamu visam uzÅÄmumam, Docz, Storybook un Styleguidist ir lieliskas iespÄjas.
No tulka. Å Ä« ir mana pirmÄ pieredze HabrÄ. Ja atrodat kÄdas neprecizitÄtes vai ir ieteikumi raksta uzlaboÅ”anai, rakstiet man personÄ«gi.
Avots: www.habr.com