Þú getur haft besta opna uppspretta verkefnið, en ef það hefur ekki góð skjöl eru líkurnar á því að það muni aldrei taka við. Á skrifstofunni mun góð skjöl koma í veg fyrir að þú svarir sömu spurningum. Skjöl tryggir einnig að fólk geti skilið verkefnið ef lykilstarfsmenn yfirgefa fyrirtækið eða hlutverk breytast. Lifandi leiðbeiningar munu hjálpa til við að tryggja heilleika gagna.
Ef þú þarft að skrifa langan texta er Markdown frábær valkostur við HTML. Stundum er Markdown setningafræði ekki nóg. Í þessu tilfelli getum við notað HTML inni í því. Til dæmis sérsniðnir þættir. Þess vegna, ef þú ert að byggja upp hönnunarkerfi með innfæddum vefhlutum, geta þeir auðveldlega verið með í textaskjölum. Ef þú ert að nota React (eða aðra JSX ramma eins og Preact eða Vue), geturðu gert það sama með MDX.
Þessi grein er víðtækt yfirlit yfir verkfæri til að skrifa skjöl og búa til leiðbeiningar. Ekki eru öll verkfærin sem talin eru upp hér nota MDX, en þau eru í auknum mæli innifalin í skjalaverkfærum.
Hvað er MDX?
skrá .mdx hefur sömu setningafræði og Markdown, en gerir þér kleift að flytja inn gagnvirka JSX íhluti og fella þá inn í efnið þitt. Stuðningur við Vue hluti er í alfa. Til að byrja að vinna með MDX skaltu bara setja upp „Create React App“. Það eru viðbætur fyrir Next.js og Gatsby. Næsta útgáfa af Docusaurus (útgáfa 2) mun einnig hafa innfæddan stuðning.
Að skrifa skjöl með Docusaurus
Docusaurus skrifaði á Facebook. Þeir nota það í öllum opnum uppspretta verkefnum nema React. Utan fyrirtækisins er það notað af Redux, Prettier, Gulp og Babel.
Verkefni sem nota Docusaurus.
Hægt er að nota Docusaurus til að skrifa allir skjöl, ekki aðeins til að lýsa framendanum. Hann er með React undir húddinu en þú þarft ekki að þekkja hann til að nota hann. Það tekur Markdown skrárnar þínar, smá töfra og vel uppbyggð, sniðin og læsileg skjöl með fallegri hönnun eru tilbúin.
Á Redux vefsíðunni er hægt að sjá staðlaða Docusaurus sniðmátið
Vefsíður byggðar með Docusaurus geta einnig innihaldið Markdown-undirstaða blogg. Prism.js er strax tengt til að auðkenna setningafræði. Þrátt fyrir þá staðreynd að Docusaurus birtist tiltölulega nýlega, var það viðurkennt sem besta tól ársins 2018 á StackShare.
Aðrir valkostir til að búa til efni
Docusaurus er sérstaklega hannað til að búa til skjöl. Auðvitað, það eru milljón og ein leiðir til að búa til vefsíðu - þú getur sett upp þína eigin lausn á hvaða tungumáli sem er, CMS, eða notað kyrrstæðan vefforrit.
Til dæmis, skjöl fyrir React, IBM hönnunarkerfi, Apollo og Ghost CMS nota Gatsby - kyrrstæður síðuframleiðandi sem oft er notaður fyrir blogg. Ef þú vinnur með Vue, þá er VuePress góður kostur fyrir þig. Annar valkostur er að nota rafall sem er skrifaður í Python - MkDocs. Það er opinn uppspretta og stilltur með einni YAML skrá. GitBook er líka góður kostur, en það er aðeins ókeypis fyrir opinber og ekki viðskiptaleg teymi. Þú getur líka einfaldlega hlaðið upp mardown skrám með Git og unnið með þær í Github.
Skjalsetningarhlutir: Docz, Storybook og Styleguidist
Leiðbeiningar, kerfishönnun, íhlutasöfn - hvað sem þú kallar þau, það hefur orðið mjög vinsælt undanfarið. Tilkoma íhlutaramma eins og React og verkfæranna sem nefnd eru hér hafa breytt þeim úr hégómaverkefnum í gagnleg verkfæri.
Storybook, Docz og Styleguidist gera allir það sama: sýna gagnvirka þætti og skjalfesta API þeirra. Verkefni getur haft tugi eða jafnvel hundruð íhluta - allir með mismunandi ástand og stíl. Ef þú vilt að íhlutir séu endurnýttir þarf fólk að vita að þeir eru til. Til að gera þetta skaltu einfaldlega skrá íhlutina. Leiðbeiningar veita auðvelt að finna yfirlit yfir alla íhlutina þína. Þetta hjálpar til við að viðhalda sjónrænni samkvæmni og forðast endurtekna vinnu.
Þessi verkfæri veita þægilega leið til að skoða mismunandi ástand. Það getur verið erfitt að endurskapa hvert ástand íhluta í samhengi við raunverulegt forrit. Í stað þess að smella á raunverulegt forrit er það þess virði að þróa sérstakan íhlut. Hægt er að líkja eftir ástandi sem erfitt er að ná til (eins og hleðsluástand).
Samhliða sjónrænni sýningu á ýmsum ríkjum og lista yfir eiginleika er oft nauðsynlegt að skrifa almenna lýsingu á innihaldinu - hönnunarrök, notkunartilvik eða lýsingar á niðurstöðum notendaprófa. Markdown er mjög auðvelt að læra - helst ættu leiðbeiningar að vera sameiginleg úrræði fyrir hönnuði og þróunaraðila. Docz, Styleguidist og Storybook bjóða upp á leið til að blanda Markdown auðveldlega saman við íhluti.
Docz
Eins og er vinnur Docz aðeins með React, en virk vinna er í gangi til að styðja við Preact, Vue og vefhluta. Docz er það nýjasta af þessum þremur verkfærum, en það hefur tekist að safna yfir 14 stjörnum á Github. Docz kynnir tvo þætti - <Playground> и < Props >. Þau eru flutt inn og notuð í skrár .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Þú getur pakkað þínum eigin React íhlutum með <Playground>til að búa til hliðstæðu af innbyggða CodePen eða CodeSandbox - það er, þú sérð íhlutinn þinn og getur breytt honum.
<Playground>
<Button>click</Button>
</Playground><Props> mun sýna allar tiltækar eignir fyrir tiltekinn React íhlut, sjálfgefin gildi og hvort eignin sé nauðsynleg.
<Props of={Button} />Persónulega finnst mér þessi MDX byggða nálgun vera auðveldast að skilja og auðveldast að vinna með.
Ef þú ert aðdáandi Gatsby kyrrstöðurafalls, býður Docz upp á frábæra samþættingu.
Stílaleiðbeiningar
Eins og Docz eru dæmi skrifuð með Markdown setningafræði. Styleguidist notar Markdown kóðablokka (þrífaldar gæsalappir) í venjulegum skrám .md skrár, ekki MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Kóðablokkir í Markdown sýna venjulega bara kóða. Þegar Styleguidist er notað, hvaða kóðablokk sem er með tungumálamerki js, jsx eða javascript mun birtast sem React hluti. Eins og Docz er kóðinn hægt að breyta - þú getur breytt eiginleikum og séð niðurstöðuna samstundis.
Styleguidist mun sjálfkrafa búa til eignatöflu úr PropTypes, Flow eða Typescript yfirlýsingum.
Styleguidist styður sem stendur React og Vue.
Sögubók
Storybook staðsetur sig sem „þróunarumhverfi HÍ íhluta. Í stað þess að skrifa dæmi íhluti inni í Markdown eða MDX skrám, skrifar þú sögur inni í Javascript skrám. Story skjalfesta tiltekið ástand íhluta. Til dæmis gæti íhlutur haft sögu fyrir hlaðið ástand og óvirkt ástand (fatlaður).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Sögubók er miklu flóknari en Styleguidist og Docz. En á sama tíma er þetta vinsælasti kosturinn; verkefnið hefur meira en 36 stjörnur á Github. Þetta er opið verkefni með 000 þátttakendum og starfsfólki í fullu starfi. Það er notað af Airbnb, Algolia, Atlassian, Lyft og Salesforce. Sögubók styður fleiri ramma en keppinautar - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte og venjulegt HTML.
Í framtíðarútgáfu verða eiginleikar frá Docz og MDX verður kynntur.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nýir eiginleikar Storybook munu koma út smám saman á næstu mánuðum og það lítur út fyrir að það verði stórt skref fram á við.
Niðurstöður
Kostir mynstursafns eru lofaðir í milljónum greina á Medium. Þegar vel er gert auðvelda þau að búa til tengdar vörur og viðhalda sjálfsmynd. Auðvitað mun ekkert af þessum tólum búa til hönnunarkerfi með töfrum. Þetta krefst vandaðrar hönnunar og CSS. En þegar kemur að því að gera hönnunarkerfi aðgengilegt öllu fyrirtækinu eru Docz, Storybook og Styleguidist frábærir kostir.
Frá þýðandanum. Þetta er fyrsta reynsla mín á Habré. Ef þú finnur einhverjar ónákvæmni, eða hefur tillögur til að bæta greinina, skrifaðu mér í persónulegum skilaboðum.
Heimild: www.habr.com