Maaari kang magkaroon ng pinakamahusay na open source na proyekto, ngunit kung wala itong mahusay na dokumentasyon, malamang na hindi ito aalis. Sa opisina, mapipigilan ka ng mahusay na dokumentasyon sa pagsagot sa parehong mga tanong. Tinitiyak din ng dokumentasyon na mauunawaan ng mga tao ang proyekto kung aalis ang mga pangunahing empleyado sa kumpanya o magbago ang mga tungkulin. Makakatulong ang mga alituntunin sa pamumuhay na matiyak ang integridad ng data.
Kung kailangan mong magsulat ng mahabang teksto, ang Markdown ay isang mahusay na alternatibo sa HTML. Minsan ang Markdown syntax ay hindi sapat. Sa kasong ito maaari naming gamitin ang HTML sa loob nito. Halimbawa, mga custom na elemento. Samakatuwid, kung bubuo ka ng isang sistema ng disenyo na may mga katutubong bahagi ng web, madali silang maisama sa dokumentasyon ng teksto. Kung gumagamit ka ng React (o anumang iba pang JSX framework tulad ng Preact o Vue), magagawa mo ang parehong bagay sa MDX.
Ang artikulong ito ay isang malawak na pangkalahatang-ideya ng mga tool para sa pagsulat ng dokumentasyon at paggawa ng mga alituntunin. Hindi lahat ng mga tool na nakalista dito ay gumagamit ng MDX, ngunit ito ay lalong isinama sa mga tool sa dokumentasyon.
Ano ang MDX?
talaksan .mdx ay may parehong syntax gaya ng Markdown, ngunit pinapayagan kang mag-import ng mga interactive na bahagi ng JSX at i-embed ang mga ito sa iyong nilalaman. Ang suporta para sa mga bahagi ng Vue ay nasa alpha. Upang magsimulang magtrabaho sa MDX, i-install lang ang "Gumawa ng React App". May mga plugin para sa Next.js at Gatsby. Ang susunod na bersyon ng Docusaurus (bersyon 2) ay magkakaroon din ng katutubong suporta.
Pagsusulat ng dokumentasyon gamit ang Docusaurus
Sumulat si Docusaurus sa Facebook. Ginagamit nila ito sa bawat open source na proyekto maliban sa React. Sa labas ng kumpanya ito ay ginagamit ng Redux, Prettier, Gulp at Babel.
Mga proyektong gumagamit ng Docusaurus.
Maaaring gamitin ang Docusaurus sa pagsulat anumang dokumentasyon, hindi lamang para ilarawan ang frontend. Mayroon itong React sa ilalim ng hood, ngunit hindi mo kailangang maging pamilyar dito upang magamit ito. Aabutin ang iyong mga Markdown file, isang kurot ng mahika at mahusay na nakabalangkas, na-format at nababasa na dokumentasyon na may magandang disenyo ay handa na.
Sa website ng Redux makikita mo ang karaniwang template ng Docusaurus
Ang mga website na binuo gamit ang Docusaurus ay maaari ding magsama ng isang Markdown-based na blog. Kaagad na konektado ang Prism.js para sa pag-highlight ng syntax. Sa kabila ng katotohanang kamakailan lamang ay lumitaw ang Docusaurus, kinilala ito bilang pinakamahusay na tool ng 2018 sa StackShare.
Iba pang Opsyon sa Paglikha ng Nilalaman
Ang Docusaurus ay partikular na idinisenyo para sa paglikha ng dokumentasyon. Siyempre, mayroong isang milyon at isang paraan upang makagawa ng isang website - maaari mong i-deploy ang iyong sariling solusyon sa anumang wika, CMS, o gumamit ng static na site generator.
Halimbawa, ang dokumentasyon para sa React, IBM design system, Apollo at Ghost CMS ay gumagamit ng Gatsby - isang static na site generator na kadalasang ginagamit para sa mga blog. Kung nagtatrabaho ka sa Vue, ang VuePress ay isang magandang opsyon para sa iyo. Ang isa pang pagpipilian ay ang paggamit ng generator na nakasulat sa Python - MkDocs. Ito ay open source at na-configure gamit ang isang YAML file. Ang GitBook ay isa ring magandang opsyon, ngunit libre lang ito para sa mga pampubliko at hindi pangkomersyal na koponan. Maaari ka ring mag-upload ng mga mardown file gamit ang Git at magtrabaho kasama ang mga ito sa Github.
Mga bahagi ng pagdodokumento: Docz, Storybook at Styleguidist
Mga alituntunin, disenyo ng system, mga library ng bahagi - anuman ang tawag mo sa kanila, ito ay naging napakapopular kamakailan. Ang pagdating ng mga component frameworks tulad ng React at ang mga tool na binanggit dito ay binago ang mga ito mula sa vanity projects tungo sa mga kapaki-pakinabang na tool.
Parehong ginagawa ang Storybook, Docz at Styleguidist: magpakita ng mga interactive na elemento at idokumento ang kanilang API. Ang isang proyekto ay maaaring magkaroon ng dose-dosenang o kahit na daan-daang bahagi - lahat ay may iba't ibang estado at istilo. Kung gusto mong magamit muli ang mga bahagi, kailangang malaman ng mga tao na mayroon sila. Upang gawin ito, i-catalog lamang ang mga bahagi. Ang mga alituntunin ay nagbibigay ng madaling mahanap na pangkalahatang-ideya ng lahat ng iyong mga bahagi. Nakakatulong ito na mapanatili ang visual consistency at maiwasan ang paulit-ulit na trabaho.
Ang mga tool na ito ay nagbibigay ng isang maginhawang paraan upang tingnan ang iba't ibang mga estado. Maaaring maging mahirap na kopyahin ang bawat estado ng isang bahagi sa konteksto ng isang tunay na aplikasyon. Sa halip na mag-click sa aktwal na application, sulit na bumuo ng isang hiwalay na bahagi. Ang mga estado na mahirap maabot (gaya ng mga estado ng pag-load) ay maaaring gayahin.
Kasama ng isang visual na pagpapakita ng iba't ibang mga estado at isang listahan ng mga pag-aari, kadalasan ay kinakailangan na magsulat ng isang pangkalahatang paglalarawan ng nilalaman - mga katwiran sa disenyo, mga kaso ng paggamit, o mga paglalarawan ng mga resulta ng pagsubok ng user. Napakadaling matutunan ng Markdown - sa isip, ang mga alituntunin ay dapat na isang nakabahaging mapagkukunan para sa mga designer at developer. Nag-aalok ang Docz, Styleguidist, at Storybook ng isang paraan upang madaling paghaluin ang Markdown sa mga bahagi.
Docz
Sa kasalukuyan, gumagana lang ang Docz sa React, ngunit ang aktibong gawain ay isinasagawa upang suportahan ang Preact, Vue at mga bahagi ng web. Ang Docz ang pinakabago sa tatlong tool, ngunit nagawa nitong mangolekta ng mahigit 14 bituin sa Github. Ipinakilala ni Docz ang dalawang bahagi β <Playground> ΠΈ < Props >. Ang mga ito ay na-import at ginagamit sa mga file .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Maaari mong balutin ang iyong sariling mga bahagi ng React <Playground>upang lumikha ng isang analogue ng built-in na CodePen o CodeSandbox - iyon ay, nakikita mo ang iyong bahagi at maaaring i-edit ito.
<Playground>
<Button>click</Button>
</Playground><Props> ipapakita ang lahat ng available na property para sa isang partikular na React component, mga default na value, at kung kinakailangan ang property.
<Props of={Button} />Sa personal, nakita kong ang diskarteng ito na nakabatay sa MDX ang pinakamadaling maunawaan at pinakamadaling gamitin.
Kung ikaw ay isang tagahanga ng Gatsby static na site generator, nag-aalok ang Docz ng isang mahusay na pagsasama.
Patnubay ng estilo
Tulad ng Docz, ang mga halimbawa ay isinulat gamit ang Markdown syntax. Gumagamit ang Styleguidist ng mga Markdown code block (triple quotes) sa mga regular na file .md mga file, hindi MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Ang mga bloke ng code sa Markdown ay karaniwang nagpapakita lamang ng code. Kapag gumagamit ng Styleguidist, anumang bloke ng code na may tag ng wika js, jsx o javascript ay magre-render bilang bahagi ng React. Tulad ng Docz, nae-edit ang code - maaari mong baguhin ang mga katangian at agad na makita ang resulta.
Awtomatikong gagawa ang Styleguidist ng property table mula sa mga deklarasyon ng PropTypes, Flow o Typescript.
Kasalukuyang sinusuportahan ng Styleguidist ang React at Vue.
Storybook
Ipinoposisyon ng Storybook ang sarili bilang isang "kapaligiran sa pag-develop ng bahagi ng UI." Sa halip na magsulat ng mga halimbawang bahagi sa loob ng Markdown o MDX file, sumulat ka mga kuwento sa loob ng mga file ng Javascript. Kuwento idokumento ang tiyak na estado ng isang bahagi. Halimbawa, ang isang bahagi ay maaaring may mga kasaysayan para sa isang na-load na estado at isang hindi pinaganang estado (hindi pinagana).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Ang Storybook ay mas kumplikado kaysa sa Styleguidist at Docz. Ngunit sa parehong oras, ito ang pinakasikat na opsyon; ang proyekto ay may higit sa 36 bituin sa Github. Ito ay isang open source na proyekto na may 000 na mga kontribyutor at full-time na kawani. Ginagamit ito ng Airbnb, Algolia, Atlassian, Lyft at Salesforce. Sinusuportahan ng Storybook ang higit pang mga framework kaysa sa mga kakumpitensya - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte at regular na HTML.
Sa isang release sa hinaharap, magkakaroon ng mga feature mula sa Docz at ipapakilala ang MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Ang mga bagong feature ng Storybook ay unti-unting lalabas sa susunod na ilang buwan at mukhang ito ay magiging isang malaking hakbang pasulong.
Mga resulta ng
Ang mga benepisyo ng isang pattern library ay pinupuri sa milyun-milyong artikulo sa Medium. Kapag ginawang mabuti, ginagawa nilang mas madali ang paggawa ng mga nauugnay na produkto at pagpapanatili ng pagkakakilanlan. Siyempre, wala sa mga tool na ito ang magically lumikha ng isang sistema ng disenyo. Nangangailangan ito ng maingat na disenyo at CSS. Ngunit pagdating ng oras upang gawing naa-access ang isang sistema ng disenyo sa buong kumpanya, ang Docz, Storybook at Styleguidist ay mahusay na mga pagpipilian.
Mula sa tagasalin. Ito ang aking unang karanasan sa HabrΓ©. Kung makakita ka ng anumang mga kamalian, o may mga mungkahi para sa pagpapabuti ng artikulo, sumulat sa akin sa isang personal na mensahe.
Pinagmulan: www.habr.com