Ju mund të keni një projekt më të mirë me burim të hapur, por nëse nuk ka dokumentacion të mirë, shanset janë që nuk do të fillojë kurrë. Në zyrë, dokumentacioni i mirë do t'ju pengojë t'u përgjigjeni të njëjtave pyetje pa pushim. Dokumentacioni gjithashtu siguron që njerëzit mund të kuptojnë projektin nëse punonjësit kryesorë largohen nga kompania ose nëse rolet ndryshojnë. Udhëzimet e drejtpërdrejta ndihmojnë në sigurimin e integritetit të të dhënave.
Nëse keni nevojë të shkruani tekst të gjatë, Markdown është një alternativë e shkëlqyer për HTML. Ndonjëherë sintaksa Markdown nuk është e mjaftueshme. Në këtë rast, ne mund të përdorim HTML brenda tij. Për shembull, elementë me porosi. Prandaj, nëse po ndërtoni një sistem dizajni me komponentë vendas të uebit, është e lehtë t'i përfshini ato në dokumentacionin e tekstit. Nëse jeni duke përdorur React (ose ndonjë kornizë tjetër JSX si Preact ose Vue), mund të bëni të njëjtën gjë me MDX.
Ky artikull është një përmbledhje e gjerë e mjeteve për shkrimin e dokumentacionit dhe krijimin e një udhëzuesi. Jo të gjitha mjetet e listuara këtu përdorin MDX, por gjithnjë e më shumë po përfshihet në mjetet e dokumentacionit.
Çfarë është MDX?
skedar .mdx ka të njëjtën sintaksë si Markdown, por ju lejon të importoni komponentë ndërveprues JSX dhe t'i futni ato në përmbajtjen tuaj. Mbështetja për komponentët Vue është në alfa. Për të filluar punën me MDX, thjesht instaloni "Create React App". Ka shtojca për Next.js dhe Gatsby. Versioni tjetër i Docusaurus (versioni 2) do të ketë gjithashtu mbështetje të integruar.
Shkrimi i dokumentacionit me Docusaurus
Docusaurus ka shkruar në Facebook. Ata e përdorin atë në çdo projekt me burim të hapur përveç React. Jashtë kompanisë, Redux, Prettier, Gulp dhe Babel e përdorin atë.
Projektet që përdorin Docusaurus.
Docusaurus mund të përdoret për të shkruar ndonjë dokumentacion, jo vetëm për të përshkruar pjesën e përparme. Ka React nën kapuç, por nuk është e nevojshme të njiheni me të për ta përdorur. Kërkon skedarët tuaj Markdown, një majë magjike dhe dokumentacion i mirëstrukturuar, i formatuar dhe i lexueshëm me një dizajn të bukur është gati.
Ju mund të shihni shabllonin e paracaktuar të Docusaurus në faqen e internetit të Redux.
Faqet e ndërtuara me Docusaurus mund të përfshijnë gjithashtu një blog të bazuar në Markdown. Për theksimin e sintaksës, Prism.js përfshihet menjëherë. Përkundër faktit se Docusaurus është shfaqur relativisht kohët e fundit, ai u njoh si mjeti më i mirë i vitit 2018 në StackShare.
Opsione të tjera të krijimit të përmbajtjes
Docusaurus është krijuar posaçërisht për krijimin e dokumentacionit. Sigurisht, ka një milion e një mënyra për të krijuar një faqe interneti - ju mund të vendosni zgjidhjen tuaj në çdo gjuhë, CMS ose të përdorni një gjenerues statik të faqes.
Për shembull, dokumentacioni për React, sistemin e projektimit IBM, Apollo dhe Ghost CMS përdorin Gatsby, një gjenerues statik faqesh që përdoret shpesh për bloge. Nëse jeni duke punuar me Vue, atëherë VuePress është një opsion i mirë për ju. Një tjetër mundësi është të përdorni një gjenerator të shkruar në Python - MkDocs. Është i hapur dhe i konfiguruar me një skedar të vetëm YAML. GitBook është gjithashtu një opsion i mirë, por është falas vetëm për ekipet e hapura dhe jokomerciale. Ju gjithashtu mund të ngarkoni skedarë mardown duke përdorur git dhe të punoni me ta në Github.
Dokumentacioni i Komponentit: Docz, Storybook dhe Styleguidist
Udhëzimet, dizajni i sistemit, bibliotekat e komponentëve, si të doni t'i quani ato, këto janë bërë shumë të njohura kohët e fundit. Shfaqja e kornizave përbërëse si React dhe mjetet e përmendura këtu ka bërë të mundur shndërrimin e tyre nga projekte të kota në mjete të dobishme.
Storybook, Docz dhe Styleguidist bëjnë të njëjtën gjë: shfaqin elementë ndërveprues dhe dokumentojnë API-në e tyre. Një projekt mund të ketë dhjetëra apo edhe qindra komponentë, të gjithë me gjendje dhe stile të ndryshme. Nëse dëshironi që komponentët të ripërdoren, njerëzit duhet të dinë se ato ekzistojnë. Për ta bërë këtë, mjafton të katalogoni komponentët. Udhëzimet ofrojnë një përmbledhje të lehtë për t'u kërkuar të të gjithë komponentëve tuaj. Kjo ndihmon në ruajtjen e konsistencës vizuale dhe shmangien e punës së përsëritur.
Këto mjete ofrojnë një mënyrë të përshtatshme për të parë gjendje të ndryshme. Mund të jetë e vështirë të përsëritet çdo gjendje e një komponenti në kontekstin e një aplikacioni real. Në vend që të klikoni në aplikacionin aktual, ia vlen të krijoni një komponent të veçantë. Është e mundur të modelohen shtete të vështira për t'u arritur (për shembull, gjendja e ngarkimit).
Së bashku me një demonstrim vizual të gjendjeve të ndryshme dhe një listë të vetive, shpesh është e nevojshme të shkruhet një përshkrim i përgjithshëm i përmbajtjes - arsyetimet e dizajnit, rastet e përdorimit ose një përshkrim i rezultateve të testimit të përdoruesit. Markdown është shumë i lehtë për t'u mësuar - në mënyrë ideale, udhëzimet duhet të jenë një burim i përbashkët për projektuesit dhe zhvilluesit. Docz, Styleguidist dhe Storybook ofrojnë një mënyrë për të përzier me lehtësi Markdown me komponentët.
Docz
Aktualisht, Docz punon vetëm me React, por po punon në mënyrë aktive në mbështetjen për komponentët Preact, Vue dhe ueb. Docz është më i fundit nga tre mjetet, por ka qenë në gjendje të mbledhë mbi 14 yje në Github. Docz prezanton dy komponentë − <Playground> и < Props >. Ato importohen dhe përdoren në skedarë .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Ju mund t'i mbështillni përbërësit tuaj React me të <Playground>për të krijuar një analog të CodePen ose CodeSandbox të integruar - domethënë, ju shihni komponentin tuaj dhe mund ta modifikoni atë.
<Playground>
<Button>click</Button>
</Playground><Props> do të tregojë të gjitha vetitë e disponueshme për komponentin e dhënë React, vlerat e paracaktuara dhe nëse prona kërkohet.
<Props of={Button} />Personalisht, më duket se kjo qasje e bazuar në MDX është më e lehta për t'u kuptuar dhe më e lehtë për të punuar.
Nëse jeni adhurues i gjeneratorit statik të faqeve të Gatsby, Docz ofron integrime të shkëlqyera.
guidist i stilit
Ashtu si në Docz, shembujt shkruhen duke përdorur sintaksën Markdown. Styleguidist përdor blloqet e kodit Markdown (thonjëza të trefishta) në skedarë të rregullt .md skedarë, jo në MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Blloqet e kodit në Markdown zakonisht tregojnë vetëm kodin. Kur përdorni Styleguidist, çdo bllok kodi me një etiketë gjuhësore js, jsx ose javascript do të shfaqet si një komponent React. Ashtu si Docz, kodi është i modifikueshëm - mund të ndryshoni vetitë dhe të shihni menjëherë rezultatin.
Styleguidist do të krijojë automatikisht një fletë pronësie nga deklaratat PropTypes, Flow ose Typescript.
Styleguidist tani mbështet React dhe Vue.
Libër me tregime
Libri i tregimeve e konsideron veten si një "mjedis i zhvillimit të komponentëve UI". Në vend që të shkruani shembuj përbërës brenda skedarëve Markdown ose MDX, ju shkruani histori brenda skedarëve Javascript. Histori dokumentoni gjendjen specifike të një komponenti. Për shembull, një komponent mund të ketë histori për një gjendje ngarkimi dhe një gjendje të çaktivizuar (i paaftë).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook është shumë më kompleks se Styleguidist dhe Docz. Por në të njëjtën kohë, ky është opsioni më i popullarizuar, në Github projekti ka më shumë se 36 yje. Ky është një projekt me burim të hapur me 000 kontribues dhe shoqërim staf. Përdoret nga Airbnb, Algolia, Atlassian, Lyft dhe Salesforce. Storybook mbështet më shumë korniza sesa konkurrenca - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte dhe HTML i thjeshtë.
Në një version të ardhshëm, do të ketë çipa nga Docz dhe MDX po prezantohet.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Veçoritë e reja të Storybook do të shfaqen gradualisht gjatë muajve të ardhshëm dhe duket se do të jetë një hap i madh përpara.
Rezultatet e
Përfitimet e bibliotekës së modeleve lavdërohen në miliona artikuj në Medium. Kur bëhen mirë, ato e bëjnë më të lehtë krijimin e produkteve të lidhura dhe ruajtjen e një identiteti. Sigurisht, asnjë nga këto mjete nuk do të krijojë në mënyrë magjike një sistem dizajni. Kjo kërkon dizajn të kujdesshëm dhe dizajn CSS. Por kur vjen koha për të vënë në dispozicion sistemin e dizajnit për të gjithë kompaninë, Docz, Storybook dhe Styleguidist janë opsione të shkëlqyera.
Nga një përkthyes. Kjo është përvoja ime e parë në Habré. Nëse gjeni ndonjë pasaktësi, ose keni sugjerime për përmirësimin e artikullit - shkruani në një personal.
Burimi: www.habr.com