Ju mund të keni projektin më të mirë me kod të hapur, por nëse ai nuk ka dokumentacion të mirë, ka mundësi që ai kurrë të mos arrijë sukses. Në zyra, dokumentacioni i mirë do ju ndihmojë të mos përgjigjeni vazhdimisht për të njëjtat pyetje. Dokumentacioni gjithashtu garanton që njerëzit mund të kuptojnë projektin nëse punonjësit kyç largohen nga kompania ose ndodhin ndryshime në rolet. Udhëzimet e gjalla do të ndihmojnë në ruajtjen e integritetit të të dhënave.
Nëse ju nevojitet të shkruani një tekst të gjatë, Markdown është një alternativë e shkëlqyer ndaj HTML. Ndonjëherë, sintaksa e Markdown s'do të mjaftojë. Në këtë rast, ne mund të përdorim HTML brenda tij. Për shembull, elementë personalizuar. Prandaj, nëse po ndërtoni një sistem dizajni me komponente web natyrale, është e lehtë t'i përfshini ato në dokumentacionin tekstual. Nëse po përdorni React (ose ndonjë tjetër framework JSX, si Preact ose Vue), ju mund të bëni të njëjtën gjë përmes MDX.
Ky artikull është një pamje e gjerë mbi mjetet për shkruajten e dokumentacionit dhe krijimin e udhëzuesve. Jo të gjitha mjetet e përmendura këtu përdorin MDX, por ai po përfshihet gjithnjë e më shumë në mjetet e dokumentacionit.
ĂfarĂ« Ă«shtĂ« MDX?
Skeda .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ështetje për komponentët Vue është në fazën alfa. Për të filluar të punoni me MDX, mjafton të instaloni "Create React App". Ka plugins për Next.js dhe Gatsby. Versioni i ardhshëm i Docusaurus (versioni 2) gjithashtu do të ketë mbështetje të integruar.
Shkrimi i dokumentacionit me Docusaurus
Docusaurus është shkruar nga Facebook. Ata e përdorin atë në çdo projekt me kod të hapur, përveç React. Jashtë kompanisë, përdoret nga Redux, Prettier, Gulp dhe Babel.
Projektet që përdorin Docusaurus.
Docusaurus mund të përdoret për të shkruar çfarëdo dokumenatacion, jo vetëm për të përshkruar front-endin. Ai ka React nën kapuç, por për ta përdorur, nuk është e nevojshme të jeni të njohur me të. Ai merr skedarët tuaj Markdown, një grimcë magjie dhe dokumentacioni i strukturuar mirë, i formatizuar dhe i lexueshëm me një dizajn të bukur është gati.
Në faqen e internetit të Redux mund të shihni modelin standard të Docusaurus
Website-të e krijuara me Docusaurus gjithashtu mund të përfshijnë një blog të bazuar në Markdown. Për theksimin e sintaksës, Prism.js është aktivizuar menjëherë. Megjithëse Docusaurus ka dalë në skenë relativisht së fundmi, ai është pranuar si mjeti më i mirë i vitit 2018 në StackShare.
Më shumë mundësi për krijimin e përmbajtjes
Docusaurus Ă«shtĂ« krijuar posaçërisht pĂ«r tĂ« krijuar dokumentacione. Natyrisht, ka miliona dhe njĂ« mĂ«nyrĂ« pĂ«r tĂ« bĂ«rĂ« njĂ« faqe â mund tĂ« vendosni zgjidhjen tuaj nĂ« çdo gjuhĂ«, CMS ose tĂ« pĂ«rdorni njĂ« gjenerues tĂ« faqeve statike.
PĂ«r shembull, dokumentacioni pĂ«r React, sistemi i dizajnit tĂ« IBM, Apollo dhe Ghost CMS pĂ«rdorin Gatsby â ky Ă«shtĂ« njĂ« gjenerues i faqeve statike, i cili shpesh pĂ«rdoret pĂ«r blogje. NĂ«se punoni me Vue, atĂ«herĂ« VuePress do tĂ« jetĂ« njĂ« opsion i mirĂ« pĂ«r ju. NjĂ« alternativĂ« tjetĂ«r Ă«shtĂ« tĂ« pĂ«rdorni njĂ« gjenerues tĂ« shkruar nĂ« Python â MkDocs. Ai Ă«shtĂ« i hapur dhe konfigurimi bĂ«het pĂ«rmes njĂ« skedari YAML. GitBook gjithashtu Ă«shtĂ« njĂ« opsion i mirĂ«, por Ă«shtĂ« falas vetĂ«m pĂ«r ekipet e hapura dhe jo-komerciale. Dhe mund tĂ« ngarkoni thjesht skedarĂ« markdown, duke pĂ«rdorur git, dhe tĂ« punoni me ta nĂ« Github.
Dokumentimi i komponenteve: Docz, Storybook dhe Styleguidist.
Rregullat, sistemet e dizajnit, bibliotekat e komponenteve â pavarĂ«sisht se si i quani ato, ato janĂ« bĂ«rĂ« shumĂ« tĂ« njohura kohĂ«t e fundit. Shfaqja e strukturave komponentiale, si React, dhe mjetet e pĂ«rmendura kĂ«tu â kanĂ« lejuar qĂ« ato tĂ« shndĂ«rrohen nga projekte vaniteti nĂ« mjete tĂ« dobishme.
Storybook, Docz dhe Styleguidist â bĂ«jnĂ« tĂ« njĂ«jtĂ«n gjĂ«: shfaqin elemente interaktive dhe dokumentojnĂ« API-tĂ« e tyre. NjĂ« projekt mund tĂ« ketĂ« dhjetĂ«ra ose madje qindra komponente â tĂ« gjitha me gjendje dhe stile tĂ« ndryshme. NĂ«se doni qĂ« komponentet tĂ« pĂ«rdoren sĂ«rish, njerĂ«zit duhet tĂ« dinĂ« se ato ekzistojnĂ«. PĂ«r kĂ«tĂ« mjafton tĂ« katalogizoni komponentet. Rregullat ofrojnĂ« njĂ« pasqyrĂ« tĂ« lehtĂ« pĂ«r t'u kĂ«rkuar pĂ«r tĂ« gjitha komponentet tuaja. Kjo ndihmon nĂ« ruajtjen e koherencĂ«s vizuale dhe shmang rekompleksitetin e punĂ«s.
Këto mjete ofrojnë një mënyrë të lehtë për të parë gjendje të ndryshme. Mund të jetë e vështirë të riprodhoni çdo gjendje të komponentit në kontekstin e një aplikacioni real. Në vend që të klikoni mbi një aplikacion real, është më mirë të zhvilloni një komponent të veçantë. Mund të modeloni gjendje të vështira për t'u arritur (p.sh., gjendja e ngarkimit).
Në përputhje me demonstrimin vizual të gjendjeve të ndryshme dhe listës së pronave, shpesh është e nevojshme të shkruhet një përshkrim i përgjithshëm të përmbajtjes - justifikimet e dizajnit, rastet e përdorimit ose përshkrimi i rezultateve të testimit të përdoruesve. Markdown është shumë e lehtë për t'u mësuar - idealisht, udhëzimet duhet të jenë një burim dhe për dizajnerët dhe për zhvilluesit. Docz, Styleguidist dhe Storybook ofrojnë një mënyrë të lehtë për të kombinuar Markdown me komponentët.
Docz
Aktualisht, Docz funksionon vetëm me React, por është duke u punuar aktivisht për mbështetje të Preact, Vue dhe komponenteve për web. Docz është më i freskët nga tre mjetet, por në Github ka arritur mbi 14,000 yje. Docz paraqet dy komponentë - <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 komponentë
Mund të mbështillni komponentët tuaj të React duke përdorur <Playground>, për të krijuar një analog të integruar CodePen ose CodeSandbox - domethënë, ju shihni komponentin tuaj dhe mund ta redaktoni atë.
<Props> do të tregojë të gjitha pronat e disponueshme për këtë komponent React, vlerat e paracaktuara dhe nëse prona është e detyrueshme.
<Props of={Button} />Personal, unë mendoj se ky qasje në bazë të MDX është më e lehtë për t'u kuptuar dhe më e lehtë për t'u punuar.
Nëse jeni një adhurues i generatorit të faqeve statike Gatsby, Docz ofron integrim të shkëlqyer.
Styleguidist
Ashtu si në Docz, shembujt shkruhen duke përdorur sintaksën Markdown. Styleguidist përdor blloqet e kodit Markdown (citatet triple) në skedarët e zakonshëm .md skedarëve, jo në MDX.
```js
Blloqet e kodit në Markdown zakonisht thjesht tregojnë kodin. Kur përdorni Styleguidist, çdo bllok kodi me etiketë gjuhe js, jsx ose javascript do të shfaqet si një komponent React. Si në Docz, kodi është i redaktueshëm - mund të ndryshoni pronat dhe të shihni menjëherë rezultatin.
Styleguidist do të krijojë automatikisht një tabelë pronash nga PropTypes, Flow ose njoftime Typescript.
Styleguidist tani mbështet React dhe Vue.
Storybook
Storybook pozicionohet si «mjedis zhvillimi për komponentët UI». Në vend që të shkruani shembuj komponentësh brenda skedarëve Markdown ose MDX, shkruani histori brenda skedarëve Javascript. Historia dokumentojnë një gjendje të caktuar të komponentit. Për shembull, një komponent mund të ketë histori për gjendjen e ngarkimit dhe gjendjen e çaktivizuar.ndaluar).
storiesOf('Button', module)
.add('ndaluar', () => (
))Storybook Ă«shtĂ« shumĂ« mĂ« i ndĂ«rlikuar se Styleguidist dhe Docz. MegjithatĂ«, Ă«shtĂ« opsioni mĂ« i njohur, me mbi 36,000 yje nĂ« Github. Ky projekt me burim tĂ« hapur pĂ«rfshin 657 kontribuues dhe mbĂ«shtetet nga staf profesionist. Ai pĂ«rdoret nga Airbnb, Algolia, Atlassian, Lyft dhe Salesforce. Storybook mbĂ«shtet mĂ« shumĂ« framework-e se konkurentĂ«t â React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte dhe HTML i zakonshĂ«m.
Në versionin e ardhshëm, do të ketë funksione 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>Funksionet e reja të Storybook do të shpërndahen gradualisht gjatë muajve të ardhshëm dhe duket se do të jetë një hap i madh përpara.
PĂ«rfundime
Avantazhet e bibliotekave të modeleve janë përmendur në miliona artikuj në Medium. Kur bëhet mirë, ato lehtësojnë krijimin e produkteve anësore dhe mbajtjen e identitetit. Sigurisht, asnjë nga këto mjete nuk do të ndihmojë magjikisht në ndërtimin e një sistemi dizajni. Kjo kërkon planifikim të kujdesshëm të dizajnit dhe CSS. Por kur vjen koha për ta bërë sistemin e dizajnit të aksesueshëm për të gjithë kompaninë, Docz, Storybook dhe Styleguidist janë opsione të shk Excellent.
Nga pĂ«rkthyesi. Ky Ă«shtĂ« eksperienca ime e parĂ« nĂ« Habr. NĂ«se keni gjetur ndonjĂ« pasaktĂ«si, ose keni sugjerime pĂ«r pĂ«rmirĂ«simin e artikullit â mos hezitoni tĂ« shkruani nĂ« mesazh privat.
Burimi: habr.com
