Ju mund të keni projektin më të mirë me kod të hapur, por nëse nuk ka dokumentacion të mirë, ka një mundësi që kurrë nuk do të arrijë sukses. Një dokumentacion i mirë në zyrë do t'ju ndihmojë të shmangni përgjigjen e të njëjtëve pyetje. Dokumentacioni gjithashtu garanton që njerëzit mund të kuptojnë projektin, nëse punonjësit kyç ikin ose rolet ndryshojnë. Udhëzimet e gjalla ndihmojnë për të siguruar integritetin e të dhënave.
Nëse duhet të shkruani një tekst të gjatë, Markdown është një alternativë e shkëlqyer për HTML. Ndonjëherë sintaksa e Markdown-it nuk është e mjaftueshme. Në këtë rast ne mund të përdorim HTML brenda tij. Për shembull, elemente të personalizuara. Prandaj, nëse po ndërtoni një sistem dizajni me komponente të reja të uebit, është e lehtë t'i përfshini ato në dokumentacionin tekstual. Nëse po përdorni React (ose ndonjë kornizë tjetër JSX, si Preact ose Vue), mund të bëni të njëjtën gjë duke përdorur MDX.
Ky artikull është një përmbledhje e gjerë e mjeteve për shkruar dokumentacion dhe krijimin e udhëzimeve. Jo të gjitha mjetet e listuara këtu përdorin MDX, por ai po përfshihet gjithnjë e më shumë në mjetet e dokumentimit.
Çfarë është MDX?
Skedari .mdx ka të njëjtën sintaksë si Markdown, por lejon importimin e komponenteve interaktive JSX dhe integrimin e tyre në përmbajtjen tuaj. Mbështetja për komponentet Vue është në alfa. Për të filluar të punoni me MDX, mjafton të instaloni "Create React App". Ka plugina 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 është shkruar nga Facebook. Ata e përdorin në çdo projekt me kod të hapur, përveç React. Jashtë kompanisë, përdoret nga Redux, Prettier, Gulp dhe Babel.
Projekte që përdorin Docusaurus.
Docusaurus mund të përdoret për të shkruar любой dokumentacion, jo vetëm për të përshkruar frontendin. Ai ka React nën kapak, por për t'u përdorur me të, nuk është e nevojshme të jeni të njohur me të. Ai merr skedarët tuaj Markdown, një gllënjkë magjie dhe dokumentacioni i strukturuar, i formatuar dhe i lexueshëm me një dizajn të bukur është gati.
Në faqen e Redux mund të shihni një model standard të Docusaurus
Faqet e krijuara me Docusaurus mund të përfshijnë gjithashtu një blog të bazuar në Markdown. Për theksimin e sintaksës, Prism.js është i përfshirë menjëherë. Pavarësisht se Docusaurus ka dalë relativisht rishtazi, ai është shpallur mjeti më i mirë i vitit 2018 në StackShare.
Opsione të tjera për krijimin e përmbajtjes
Docusaurus është projektuar posaçërisht për krijimin e dokumentacionit. Natyrisht, ka një milion e një mënyra për të krijuar një faqe — mund të vendosni zgjidhjen tuaj në çdo gjuhë, CMS ose përdorni një gjenerator faqesh statike.
Për shembull, dokumentacioni për React, sistemi dizajni i IBM, Apollo dhe Ghost CMS përdorin Gatsby — kjo është një gjenerator faqesh statike që shpesh përdoret për blogje. Nëse po punoni me Vue, VuePress do t'ju shërbejë si një mundësi e mirë. Një alternativë tjetër është të përdorni një gjenerator të shkruar në Python — MkDocs. Ai është i hapur dhe konfigurohet me një skedë YAML. GitBook gjithashtu është një alternativë e mirë, por është falas vetëm për ekipet me kod të hapur dhe jo fitimprurëse. Gjithashtu mund të ngarkoni skedarë Markdown, duke përdorur git, dhe të punoni me ta në Github.
Dokumentimi i komponenteve: Docz, Storybook dhe Styleguidist
Udhëzimet, sistemet e dizajnit, bibliotekat e komponentëve — siç i quani, ato janë bërë shumë të njohura kohët e fundit. Pavarësisht nga shfaqja e kornizave komponentësh, si React dhe mjetet e përmendura këtu — kanë bërë që ato të kalojnë nga projekte të kota në mjete të dobishme.
Storybook, Docz dhe Styleguidist bëjnë të njëjtën gjë: shfaqin elemente interaktive dhe dokumentojnë API-në e tyre. Një projekt mund të ketë dhjetëra ose madje qindra komponente — të gjitha me gjendje dhe stile të ndryshme. Nëse dëshironi që komponentët të përdoren përsëri, njerëzit duhet të dinë se ekzistojnë. Për këtë, mjafton të katalogizoni komponentët. Udhëzimet ofrojnë një përmbledhje të lehtë për t'u kërkuar të gjitha komponentët tuaj. Kjo ndihmon në ruajtjen e qëndrueshmërisë vizuale dhe shmangjen e punës së përsëritur.
Këto mjete ofrojnë një mënyrë të përshtatshme për të parë gjendjet e ndryshme. Mund të jetë e vështirë të riprodhoni çdo gjendje të komponentit në kontekstin e një aplikacioni real. Në vend që të klikoni në një aplikacion të vërtetë, ia vlen të zhvilloni një komponent të veçantë. Mund të simuloni gjendje të pakta të arritshme (për shembull, gjendja e ngarkesës).
Së bashku me demonstrimin vizual të ndryshimeve dhe listën e veçorive, shpesh është e nevojshme të shkruhet një përshkrim i përgjithshëm i përmbajtjes — arsyetimi i dizajnit, rastet e përdorimit ose përshkrimi i rezultateve të testimeve për përdoruesit. Markdown është shumë i lehtë për t'u mësuar — idealisht, udhëzuesit duhet të jenë një burim i përbashkët për dizajnerët dhe zhvilluesit. Docz, Styleguidist dhe Storybook ofrojnë një mënyrë të lehtë për të kombinuar Markdown me komponente.
Docz
Aktualisht Docz funksionon vetëm me React, por është duke u punuar aktivisht për mbështetje për Preact, Vue dhe komponentë web. Docz është më i freskët nga tre mjetet, por në Github ka grumbulluar më shumë se 14,000 yje. Docz paraqet dy componente — <Playground> dhe < Props >. Ato importohen dhe përdoren në skedarët .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## Mund të _shkruani_ **markdown**
### Mund të importoni dhe përdorni komponente
Mund të mbështillni komponentët tuaj të React me <Playground>, për të krijuar një analog të CodePen ose CodeSandbox — domethënë, shihni komponentin tuaj dhe mund ta redaktoni atë.
<Props> do të tregojë të gjitha veçoritë e disponueshme për këtë komponent React, vlerat e paracaktuara dhe nëse veçoria kërkohet.
<Props of={Button} />Personalish, mendoj se ky qasje mbi MDX është më e lehtë për t'u kuptuar dhe më e thjeshtë për t'u punuar.
Nëse jeni adhurues i gjeneratorit të faqeve statike Gatsby, Docz ofron një integrim të shkëlqyer.
Styleguidist
Si në Docz, shembujt shkruhen duke përdorur sintaksën Markdown. Styleguidist përdor blloqe kodi Markdown (citatet e trefishta) në skedarët e zakonshëm .md në vend që në MDX.
```js
```Blloqet e kodit në Markdown zakonisht tregojnë thjesht kod. Kur përdorni Styleguidist, çdo bllok kodi me etiketën e gjuhës js, jsx ose javascript do të paraqitet si një komponent React. Si në Docz, kodi është i redaktueshëm — mund të ndryshoni veçoritë dhe të shihni menjëherë rezultatin.
Styleguidist automatikisht do të krijojë një tabelë veçorish nga deklaratat e PropTypes, Flow ose Typescript.
Styleguidist aktualisht mbështet React dhe Vue.
Storybook
Storybook pozicionohet si "mjedisi i zhvillimit të komponenteve UI". Në vend që të shkruani shembuj komponentësh brenda skedarëve Markdown ose MDX, shkruani historia në skedarët Javascript. Historia dokumentojnë gjendjen specifike të komponentit. Për shembull, një komponent mund të ketë histori për gjendjen e ngarkesës dhe gjendjen e çaktivizuar (disabled).
storiesOf('Button', module)
.add('disabled', () => (
))Storybook është shumë më i komplikuar se Styleguidist dhe Docz. Megjithatë, kjo është opsioni më popullor, me më shumë se 36,000 yje në Github. Ky është një projekt me kod të hapur, me 657 kontribues dhe mbështetje nga stafi i brendshëm. Përdoret nga Airbnb, Algolia, Atlassian, Lyft dhe Salesforce. Storybook mbështet më shumë framework-e se konkurrentët — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte dhe HTML të zakonshëm.
Në versionin e ardhshëm do të ketë veçori nga Docz dhe do të integrohet MDX.
# 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.
Përfundimet
Avantazhet e bibliotekave të modele prevalojnë në miliona artikuj në Medium. Kur çdo gjë bëhet mirë, ato lehtësojnë krijimin e produkteve të ngjashme dhe ruajtjen e identitetit. Sigurisht, asnjë nga këto mjete nuk do të ndihmojë në mënyrë magjike për të krijuar një sistem dizajni. Kjo kërkon ndihmë të kujdesshme të dizajnit dhe CSS. Por kur vjen koha për ta bërë sistemin e dizajnit të disponueshëm për tërë kompaninë, Docz, Storybook dhe Styleguidist janë opsione të shkëlqyera.
Nga përkthyesi. Ky është përvoja ime e parë në Habr. Nëse keni gjetur ndonjë pasaktësi, ose keni sugjerime për përmirësimin e artikullit — shkruani në inbox.
Burimi: habr.com
