Gallwch chi gael y prosiect ffynhonnell agored gorau, ond os nad oes ganddo ddogfennaeth dda, mae'n debygol na fydd byth yn dechrau. Yn y swyddfa, bydd dogfennaeth dda yn eich atal rhag ateb yr un cwestiynau. Mae dogfennaeth hefyd yn sicrhau y gall pobl ddeall y prosiect os bydd gweithwyr allweddol yn gadael y cwmni neu os bydd rolau'n newid. Bydd canllawiau byw yn helpu i sicrhau cywirdeb data.
Os oes angen i chi ysgrifennu testun hir, mae Markdown yn ddewis arall gwych i HTML. Weithiau nid yw cystrawen Markdown yn ddigon. Yn yr achos hwn gallwn ddefnyddio HTML y tu mewn iddo. Er enghraifft, elfennau arferiad. Felly, os ydych chi'n adeiladu system ddylunio gyda chydrannau gwe brodorol, gellir eu cynnwys yn hawdd mewn dogfennaeth testun. Os ydych chi'n defnyddio React (neu unrhyw fframwaith JSX arall fel Preact neu Vue), gallwch chi wneud yr un peth gydag MDX.
Mae'r erthygl hon yn drosolwg eang o offer ar gyfer ysgrifennu dogfennaeth a chreu canllawiau. Nid yw pob un o'r offer a restrir yma yn defnyddio MDX, ond mae'n cael ei gynnwys fwyfwy mewn offer dogfennu.
Beth yw MDX?
file .mdx Γ’'r un gystrawen Γ’ Markdown, ond mae'n caniatΓ‘u ichi fewnforio cydrannau rhyngweithiol JSX a'u hymgorffori yn eich cynnwys. Mae cefnogaeth ar gyfer cydrannau Vue mewn alffa. I ddechrau gweithio gyda MDX, gosodwch βCreate React Appβ. Mae ategion ar gyfer Next.js a Gatsby. Bydd gan y fersiwn nesaf o Docusaurus (fersiwn 2) gefnogaeth frodorol hefyd.
Ysgrifennu dogfennaeth gyda Docusaurus
Ysgrifennodd Docusaurus ar Facebook. Maent yn ei ddefnyddio ar bob prosiect ffynhonnell agored ac eithrio React. Y tu allan i'r cwmni fe'i defnyddir gan Redux, Prettier, Gulp a Babel.
Prosiectau sy'n defnyddio Docusaurus.
Gellir defnyddio Docwsaurus i ysgrifennu unrhyw dogfennaeth, nid yn unig i ddisgrifio'r blaen. Mae ganddo React o dan y cwfl, ond nid oes rhaid i chi fod yn gyfarwydd ag ef i'w ddefnyddio. Mae'n cymryd eich ffeiliau Markdown, mae pinsiad o hud a dogfennaeth wedi'i strwythuro'n dda, wedi'i fformatio ac yn ddarllenadwy gyda dyluniad hardd yn barod.
Ar wefan Redux gallwch weld y templed safonol Docusaurus
Gall gwefannau a adeiladwyd gyda Docusaurus hefyd gynnwys blog yn seiliedig ar Markdown. Mae Prism.js wedi'i gysylltu ar unwaith ar gyfer amlygu cystrawen. Er gwaethaf y ffaith bod Docusaurus wedi ymddangos yn gymharol ddiweddar, fe'i cydnabuwyd fel yr offeryn gorau o 2018 ar StackShare.
Opsiynau Creu Cynnwys Eraill
Mae Docusaurus wedi'i gynllunio'n benodol ar gyfer creu dogfennaeth. Wrth gwrs, mae yna filiwn ac un o ffyrdd o wneud gwefan - gallwch chi ddefnyddio'ch datrysiad eich hun mewn unrhyw iaith, CMS, neu ddefnyddio generadur safle sefydlog.
Er enghraifft, mae dogfennaeth ar gyfer React, system ddylunio IBM, Apollo a Ghost CMS yn defnyddio Gatsby - generadur safle sefydlog a ddefnyddir yn aml ar gyfer blogiau. Os ydych chi'n gweithio gyda Vue, yna mae VuePress yn opsiwn da i chi. Opsiwn arall yw defnyddio generadur a ysgrifennwyd yn Python - MkDocs. Mae'n ffynhonnell agored ac wedi'i ffurfweddu gan ddefnyddio un ffeil YAML. Mae GitBook hefyd yn opsiwn da, ond dim ond i dimau cyhoeddus ac anfasnachol y mae am ddim. Gallwch hefyd uwchlwytho ffeiliau mardown gan ddefnyddio Git a gweithio gyda nhw yn Github.
Cydrannau dogfennu: Docz, Storybook a Styleguidist
Canllawiau, cynllun system, llyfrgelloedd cydrannau - beth bynnag rydych chi'n eu galw, mae wedi dod yn boblogaidd iawn yn ddiweddar. Mae dyfodiad fframweithiau cydran fel React a'r offer a grybwyllir yma wedi eu trawsnewid o brosiectau gwagedd yn offer defnyddiol.
Mae Storybook, Docz a Styleguidist i gyd yn gwneud yr un peth: arddangos elfennau rhyngweithiol a dogfennu eu API. Gall fod gan brosiect ddwsinau neu hyd yn oed gannoedd o gydrannau - pob un Γ’ chyflyrau ac arddulliau gwahanol. Os ydych chi am i gydrannau gael eu hailddefnyddio, mae angen i bobl wybod eu bod yn bodoli. I wneud hyn, catalogiwch y cydrannau. Mae canllawiau yn rhoi trosolwg hawdd ei ddarganfod o'ch holl gydrannau. Mae hyn yn helpu i gynnal cysondeb gweledol ac osgoi gwaith ailadroddus.
Mae'r offer hyn yn darparu ffordd gyfleus i weld gwahanol daleithiau. Gall fod yn anodd atgynhyrchu pob cyflwr o gydran yng nghyd-destun cymhwysiad go iawn. Yn hytrach na chlicio ar y cais ei hun, mae'n werth datblygu cydran ar wahΓ’n. Gellir efelychu cyflyrau anodd eu cyrraedd (fel cyflyrau llwytho).
Ynghyd ag arddangosiad gweledol o wahanol gyflyrau a rhestr o briodweddau, yn aml mae angen ysgrifennu disgrifiad cyffredinol o'r cynnwys - rhesymeg dylunio, achosion defnydd, neu ddisgrifiadau o ganlyniadau profion defnyddwyr. Mae Markdown yn hawdd iawn i'w ddysgu - yn ddelfrydol, dylai canllawiau fod yn adnodd a rennir ar gyfer dylunwyr a datblygwyr. Mae Docz, Styleguidist, a Storybook yn cynnig ffordd o gymysgu Markdown Γ’ chydrannau yn hawdd.
Docz
Ar hyn o bryd dim ond gydag React y mae Docz yn gweithio, ond mae gwaith gweithredol ar y gweill i gefnogi Preact, Vue a chydrannau gwe. Docz ywβr diweddaraf oβr tri theclyn, ond mae wedi llwyddo i gasglu dros 14 o sΓͺr ar Github. Mae Docz yn cyflwyno dwy gydran - <Playground> ΠΈ < Props >. Maent yn cael eu mewnforio a'u defnyddio mewn ffeiliau .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Gallwch lapio'ch cydrannau React eich hun Γ’ nhw <Playground>i greu analog o'r CodePen neu CodeSandbox adeiledig - hynny yw, rydych chi'n gweld eich cydran ac yn gallu ei golygu.
<Playground>
<Button>click</Button>
</Playground><Props> yn dangos yr holl eiddo sydd ar gael ar gyfer cydran React benodol, gwerthoedd rhagosodedig, ac a oes angen yr eiddo.
<Props of={Button} />Yn bersonol, mae'r dull hwn sy'n seiliedig ar MDX yn fy marn i yw'r hawsaf i'w ddeall a'r hawsaf i weithio ag ef.
Os ydych chi'n gefnogwr o gynhyrchydd safle sefydlog Gatsby, mae Docz yn cynnig integreiddiad gwych.
Canllaw arddull
Fel Docz, ysgrifennir enghreifftiau gan ddefnyddio cystrawen Markdown. Mae Styleguidist yn defnyddio blociau cod Markdown (dyfynbrisiau triphlyg) mewn ffeiliau rheolaidd .md ffeiliau, nid MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Mae blociau cod yn Markdown fel arfer yn dangos cod yn unig. Wrth ddefnyddio Styleguidist, unrhyw floc o god gyda thag iaith js, jsx neu javascript yn rendro fel cydran React. Fel Docz, mae modd golygu'r cod - gallwch chi newid priodweddau a gweld y canlyniad ar unwaith.
Bydd Styleguidist yn creu tabl priodweddau yn awtomatig o ddatganiadau PropTypes, Llif neu Deipysgrif.
Ar hyn o bryd mae Styleguidist yn cefnogi React a Vue.
Llyfr Stori
Mae'r Llyfr Stori yn gosod ei hun fel βamgylchedd datblygu cydrannau UI.β Yn lle ysgrifennu cydrannau enghreifftiol y tu mewn i ffeiliau Markdown neu MDX, rydych chi'n ysgrifennu hanes y tu mewn i ffeiliau Javascript. Stori dogfennu cyflwr penodol cydran. Er enghraifft, efallai bod gan gydran hanesion cyflwr llwythog a chyflwr anabl (anabl).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Mae Storybook yn llawer mwy cymhleth na Styleguidist a Docz. Ond ar yr un pryd, dyma'r opsiwn mwyaf poblogaidd; mae gan y prosiect fwy na 36 o sΓͺr ar Github. Mae'n brosiect ffynhonnell agored gyda 000 o gyfranwyr a staff llawn amser. Fe'i defnyddir gan Airbnb, Algolia, Atlassian, Lyft a Salesforce. Mae Storybook yn cefnogi mwy o fframweithiau na chystadleuwyr - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte a HTML rheolaidd.
Mewn datganiad yn y dyfodol bydd nodweddion gan Docz a bydd MDX yn cael eu cyflwyno.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Bydd nodweddion newydd Storybook yn cael eu cyflwyno'n raddol dros y misoedd nesaf ac mae'n edrych yn debyg y bydd yn gam mawr ymlaen.
Canlyniadau
Mae manteision llyfrgell batrwm yn cael eu canmol mewn miliynau o erthyglau ar Ganolig. Pan gΓ’nt eu gwneud yn dda, maent yn ei gwneud hi'n haws creu cynhyrchion cysylltiedig a chynnal hunaniaeth. Wrth gwrs, ni fydd yr un o'r offer hyn yn creu system ddylunio hudol. Mae hyn yn gofyn am ddylunio gofalus a CSS. Ond pan ddaw'n amser gwneud system ddylunio yn hygyrch i'r cwmni cyfan, mae Docz, Storybook a Styleguidist yn opsiynau gwych.
Oddiwrth y cyfieithydd. Dyma fy mhrofiad cyntaf ar HabrΓ©. Os byddwch yn dod o hyd i unrhyw anghywirdebau, neu os oes gennych awgrymiadau ar gyfer gwella'r erthygl, ysgrifennwch ataf mewn neges bersonol.
Ffynhonnell: hab.com