Galbūt turite geresnį atvirojo kodo projektą, bet jei jis neturi geros dokumentacijos, tikėtina, kad jis niekada nepasireikš. Biure geri dokumentai neleis jums nuolat atsakyti į tuos pačius klausimus. Dokumentacija taip pat užtikrina, kad žmonės galėtų suprasti projektą, jei pagrindiniai darbuotojai palieka įmonę arba pasikeičia vaidmenys. Tiesioginės gairės padeda užtikrinti duomenų vientisumą.
Jei reikia rašyti ilgą tekstą, Markdown yra puiki alternatyva HTML. Kartais Markdown sintaksės nepakanka. Tokiu atveju jo viduje galime naudoti HTML. Pavyzdžiui, pasirinktiniai elementai. Todėl, jei kuriate projektavimo sistemą su vietiniais žiniatinklio komponentais, nesunku juos įtraukti į tekstinę dokumentaciją. Jei naudojate „React“ (arba bet kurią kitą JSX sistemą, pvz., „Preact“ ar „Vue“, tą patį galite padaryti naudodami MDX.
Šis straipsnis yra plati dokumentų rašymo ir gairių kūrimo įrankių apžvalga. Ne visi čia išvardyti įrankiai naudoja MDX, tačiau jis vis dažniau įtraukiamas į dokumentacijos įrankius.
Kas yra MDX?
byla .mdx turi tą pačią sintaksę kaip Markdown, bet leidžia importuoti interaktyvius JSX komponentus ir įterpti juos į turinį. „Vue“ komponentų palaikymas yra alfa versijos. Norėdami pradėti dirbti su MDX, tiesiog įdiekite „Create React App“. Yra „Next.js“ ir „Gatsby“ įskiepiai. Kita Docusaurus versija (2 versija) taip pat turės integruotą palaikymą.
Dokumentacijos rašymas su Docusaurus
Docusaurus rašė Facebook. Jie jį naudoja kiekviename atvirojo kodo projekte, išskyrus „React“. Už įmonės ribų jį naudoja Redux, Prettier, Gulp ir Babel.
Projektai, kuriuose naudojamas Docusaurus.
Docusaurus galima naudoti rašant bet koks dokumentacija, o ne tik sąsajos aprašymas. Po gaubtu yra „React“, bet nebūtina su juo būti susipažinęs, kad galėtumėte jį naudoti. Tam reikia jūsų „Markdown“ failų, žiupsnelis magijos ir geros struktūros, suformatuoti ir skaitomi gražaus dizaino dokumentai.
Numatytąjį Docusaurus šabloną galite pamatyti Redux svetainėje.
Svetainėse, sukurtose naudojant „Docusaurus“, taip pat gali būti „Markdown“ tinklaraščio. Sintaksės paryškinimui Prism.js iš karto įtraukiamas. Nepaisant to, kad „Docusaurus“ pasirodė palyginti neseniai, „StackShare“ jis buvo pripažintas geriausiu 2018 m.
Kitos turinio kūrimo parinktys
Docusaurus yra specialiai sukurtas dokumentacijai kurti. Žinoma, yra milijonas ir vienas būdas sukurti svetainę – galite įdiegti savo sprendimą bet kuria kalba, TVS arba naudoti statinį svetainių generatorių.
Pavyzdžiui, „React“, IBM projektavimo sistemos, „Apollo“ ir „Ghost CMS“ dokumentacijoje naudojamas „Gatsby“ – statinis svetainių generatorius, dažnai naudojamas tinklaraščiams. Jei dirbate su „Vue“, „VuePress“ yra geras pasirinkimas. Kitas variantas – naudoti Python parašytą generatorių – MkDocs. Jis atidarytas ir sukonfigūruotas vienu YAML failu. „GitBook“ taip pat yra geras pasirinkimas, tačiau jis nemokamas tik atviroms ir nekomercinėms komandoms. Taip pat galite tiesiog įkelti „mardown“ failus naudodami „git“ ir dirbti su jais „Github“.
Komponentų dokumentacija: Docz, Storybook ir Stylegudist
Gairės, sistemos dizainas, komponentų bibliotekos, kaip norite jas pavadinti, pastaruoju metu labai išpopuliarėjo. Atsiradus komponentų sistemoms, tokioms kaip „React“, ir čia paminėtos priemonės leido jas iš tuščiažodžiavimo projektų paversti naudingais įrankiais.
Storybook, Docz ir Styleguidist daro tą patį: rodo interaktyvius elementus ir dokumentuoja jų API. Projekte gali būti dešimtys ar net šimtai komponentų, kurių visų būsenos ir stiliai skiriasi. Jei norite, kad komponentai būtų naudojami pakartotinai, žmonės turi žinoti, kad jie egzistuoja. Norėdami tai padaryti, pakanka komponentus kataloguoti. Gairėse pateikiama lengvai ieškoma visų jūsų komponentų apžvalga. Tai padeda išlaikyti vizualinį nuoseklumą ir išvengti pasikartojančio darbo.
Šios priemonės leidžia patogiai peržiūrėti įvairias būsenas. Gali būti sunku pakartoti kiekvieną komponento būseną realios programos kontekste. Užuot spustelėjus tikrąją programą, verta sukurti atskirą komponentą. Galima modeliuoti sunkiai pasiekiamas būsenas (pavyzdžiui, pakrovimo būseną).
Kartu su vaizdiniu įvairių būsenų demonstravimu ir savybių sąrašu, dažnai reikia parašyti bendrą turinio aprašymą – dizaino pagrindimą, naudojimo atvejus ar vartotojo testavimo rezultatų aprašymą. „Markdown“ labai lengva išmokti – idealiu atveju gairės turėtų būti bendras dizainerių ir kūrėjų šaltinis. „Docz“, „Stylegudist“ ir „Storybook“ siūlo būdą, kaip lengvai sumaišyti „Markdown“ su komponentais.
Docz
Šiuo metu „Docz“ veikia tik su „React“, tačiau aktyviai dirba su „Preact“, „Vue“ ir žiniatinklio komponentų palaikymu. „Docz“ yra naujausias iš trijų įrankių, tačiau „Github“ galėjo surinkti daugiau nei 14 000 žvaigždučių. Docz pristato du komponentus − <Playground> и < Props >. Jie importuojami ir naudojami failuose .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Galite apvynioti savo „React“ komponentus <Playground>sukurti integruoto CodePen arba CodeSandbox analogą – tai yra, matote savo komponentą ir galite jį redaguoti.
<Playground>
<Button>click</Button>
</Playground><Props> parodys visas galimas nurodyto React komponento ypatybes, numatytąsias reikšmes ir tai, ar ypatybė reikalinga.
<Props of={Button} />Asmeniškai manau, kad šis MDX pagrįstas metodas yra lengviausiai suprantamas ir lengviausias su juo dirbti.
Jei esate „Gatsby“ statinio svetainių generatoriaus gerbėjas, „Docz“ siūlo puikias integracijas.
stiliaus vadovas
Kaip ir Docz, pavyzdžiai parašyti naudojant Markdown sintaksę. Stylegudist naudoja Markdown kodo blokus (trigubas kabutes) įprastuose failuose .md failus, o ne MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>„Markdown“ kodo blokai paprastai tik rodo kodą. Naudojant Styleguidist, bet koks kodo blokas su kalbos žyma js, jsx arba javascript bus rodomas kaip „React“ komponentas. Kaip ir Docz, kodą galima redaguoti – galite keisti savybes ir akimirksniu matyti rezultatą.
Styleguidist automatiškai sukurs ypatybių lapą iš PropTypes, Flow arba Typescript deklaracijų.
„Styleguidist“ dabar palaiko „React“ ir „Vue“.
Pasakų knyga
Pasakojimų knyga save vadina „UI komponentų kūrimo aplinka“. Užuot rašę komponentų pavyzdžius Markdown arba MDX failuose, rašykite istorijos Javascript failų viduje. Istorija dokumentuokite konkrečią komponento būseną. Pavyzdžiui, komponentas gali turėti pakrovimo būsenos ir išjungtos būsenos istorijas (invalidai).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Pasakojimų knyga yra daug sudėtingesnė nei Stylegudist ir Docz. Tačiau tuo pačiu metu tai yra populiariausias variantas, „Github“ projektas turi daugiau nei 36 000 žvaigždučių. Tai atvirojo kodo projektas, kuriame dalyvauja 657 bendradarbiai ir darbuotojai. Jį naudoja Airbnb, Algolia, Atlassian, Lyft ir Salesforce. Storybook palaiko daugiau sistemų nei konkurentai – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte ir paprastą HTML.
Būsimame leidime bus „Docz“ lustai ir pristatomas MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Naujos Storybook funkcijos bus palaipsniui įdiegtos per ateinančius kelis mėnesius ir atrodo, kad tai bus didelis žingsnis į priekį.
rezultatai
Modelių bibliotekos pranašumai giriami milijonuose straipsnių apie „Medium“. Gerai atlikus juos lengviau kurti susijusius produktus ir išlaikyti tapatybę. Žinoma, nė vienas iš šių įrankių stebuklingai nesukurs dizaino sistemos. Tam reikia kruopštaus dizaino ir CSS dizaino. Tačiau kai ateina laikas padaryti dizaino sistemą prieinamą visai įmonei, „Docz“, „Storybook“ ir „Styleguidist“ yra puikios galimybės.
Iš vertėjo. Tai mano pirmoji patirtis su Habré. Jei radote netikslumų ar turite pasiūlymų, kaip patobulinti straipsnį - rašykite asmeniškai.
Šaltinis: www.habr.com