Teil võib olla parim avatud lähtekoodiga projekt, kuid kui sellel pole head dokumentatsiooni, ei saa see tõenäoliselt kunagi käiku. Kontoris takistab hea dokumentatsioon samadele küsimustele vastamast. Dokumentatsioon tagab ka selle, et inimesed saavad projektist aru, kui võtmetöötajad ettevõttest lahkuvad või rollid muutuvad. Elujuhised aitavad tagada andmete terviklikkuse.
Kui teil on vaja kirjutada pikka teksti, on Markdown suurepärane alternatiiv HTML-ile. Mõnikord Markdowni süntaksist ei piisa. Sel juhul saame selle sees kasutada HTML-i. Näiteks kohandatud elemendid. Seega, kui loote oma veebikomponentidega disainisüsteemi, saate need hõlpsasti tekstidokumentatsiooni lisada. Kui kasutate Reacti (või mõnda muud JSX-i raamistikku, nagu Preact või Vue), saate sama teha ka MDX-iga.
See artikkel on põhjalik ülevaade dokumentide kirjutamise ja juhiste koostamise tööriistadest. Mitte kõik siin loetletud tööriistad ei kasuta MDX-i, kuid seda lisatakse üha enam dokumenteerimistööriistadesse.
Mis on MDX?
fail .mdx on sama süntaksiga kui Markdown, kuid võimaldab teil importida interaktiivseid JSX-i komponente ja manustada need oma sisusse. Vue komponentide tugi on alfa-vormingus. MDX-iga töötamise alustamiseks installige lihtsalt "Loo React App". Next.js ja Gatsby jaoks on pluginad. Docusauruse järgmisel versioonil (versioon 2) on ka algne tugi.
Dokumentatsiooni kirjutamine Docusaurusega
Docusaurus kirjutas Facebookis. Nad kasutavad seda kõigis avatud lähtekoodiga projektides, välja arvatud React. Väljaspool ettevõtet kasutavad seda Redux, Prettier, Gulp ja Babel.
Docusaurust kasutavad projektid.
Docusaurust saab kasutada kirjutamiseks iga dokumentatsiooni, mitte ainult esiserva kirjeldamiseks. Selle kapoti all on React, kuid selle kasutamiseks ei pea te sellega tuttav olema. See võtab teie Markdowni failid, näputäis maagiat ja hästi struktureeritud, vormindatud ja loetav kauni kujundusega dokumentatsioon on valmis.
Reduxi veebisaidil näete standardset Docusauruse malli
Docusaurusega loodud veebisaidid võivad sisaldada ka Markdowni-põhist ajaveebi. Prism.js ühendatakse kohe süntaksi esiletõstmiseks. Hoolimata asjaolust, et Docusaurus ilmus suhteliselt hiljuti, tunnistati see StackShare'is 2018. aasta parimaks tööriistaks.
Muud sisu loomise valikud
Docusaurus on spetsiaalselt loodud dokumentatsiooni loomiseks. Loomulikult on veebisaidi tegemiseks miljon ja üks viise – saate juurutada oma lahenduse mis tahes keeles, CMS-is või kasutada staatilist saidigeneraatorit.
Näiteks Reacti, IBMi disainisüsteemi, Apollo ja Ghost CMS-i dokumentatsioonis kasutatakse Gatsbyt – staatilist saidigeneraatorit, mida sageli kasutatakse ajaveebide jaoks. Kui töötate Vuega, on VuePress teie jaoks hea valik. Teine võimalus on kasutada Pythonis kirjutatud generaatorit – MkDocs. See on avatud lähtekoodiga ja konfigureeritud ühe YAML-faili abil. GitBook on samuti hea valik, kuid see on tasuta ainult avalikele ja mitteärilistele meeskondadele. Samuti saate lihtsalt Giti abil mardown-faile üles laadida ja nendega Githubis töötada.
Dokumenteerimiskomponendid: Docz, Storybook ja Styleguidist
Juhised, süsteemikujundus, komponentide teegid – kuidas neid ka ei nimetata, on see viimasel ajal väga populaarseks muutunud. Komponentraamistike nagu React ja siin mainitud tööriistade tulek on muutnud need edevusprojektidest kasulikeks tööriistadeks.
Storybook, Docz ja Styleguidist teevad kõik sama: kuvavad interaktiivseid elemente ja dokumenteerivad nende API. Projektil võib olla kümneid või isegi sadu komponente – kõik erineva oleku ja stiiliga. Kui soovite komponente uuesti kasutada, peavad inimesed teadma, et need on olemas. Selleks kataloogige lihtsalt komponendid. Juhised annavad hõlpsasti leitava ülevaate kõigist teie komponentidest. See aitab säilitada visuaalset järjepidevust ja vältida korduvat tööd.
Need tööriistad pakuvad mugavat võimalust erinevate olekute vaatamiseks. Reaalse rakenduse kontekstis võib komponendi iga oleku reprodutseerimine olla keeruline. Selle asemel, et klõpsata tegelikul rakendusel, tasub välja töötada eraldi komponent. Raskesti ligipääsetavaid olekuid (nt laadimisolekuid) saab simuleerida.
Erinevate olekute visuaalse demonstreerimise ja omaduste loendi kõrval on sageli vaja kirjutada sisu üldine kirjeldus – disaini põhjendused, kasutusjuhtumid või kasutajatestide tulemuste kirjeldused. Markdowni on väga lihtne õppida – ideaaljuhul peaksid juhised olema disainerite ja arendajate jagatud ressurss. Docz, Styleguidist ja Storybook pakuvad võimalust Markdowni hõlpsaks segamiseks komponentidega.
Docz
Praegu töötab Docz ainult Reactiga, kuid käimas on aktiivne töö Preacti, Vue ja veebikomponentide toetamiseks. Docz on kolmest tööriistast uusim, kuid see on suutnud Githubis koguda üle 14 000 tärni. Docz tutvustab kahte komponenti − <Playground> и < Props >. Neid imporditakse ja kasutatakse failides .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Saate oma Reacti komponente mähkida <Playground>sisseehitatud CodePeni või CodeSandboxi analoogi loomiseks - see tähendab, et näete oma komponenti ja saate seda redigeerida.
<Playground>
<Button>click</Button>
</Playground><Props> kuvab kõik antud Reacti komponendi saadaolevad atribuudid, vaikeväärtused ja kas atribuut on nõutav.
<Props of={Button} />Isiklikult leian, et see MDX-põhine lähenemine on kõige lihtsam mõista ja kõige lihtsam töötada.
Kui olete Gatsby staatilise saidi generaatori fänn, pakub Docz suurepärast integratsiooni.
Stiilijuhend
Nagu Docz, on ka näited kirjutatud Markdowni süntaksi abil. Styleguidist kasutab tavafailides Markdowni koodiplokke (kolmekordseid jutumärke). .md failid, mitte MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Markdowni koodiplokid näitavad tavaliselt lihtsalt koodi. Styleguidisti kasutamisel suvaline keelesildiga koodiplokk js, jsx või javascript renderdatakse React komponendina. Sarnaselt Doczile on kood redigeeritav – saate omadusi muuta ja tulemust koheselt näha.
Styleguidist loob PropTypes, Flow või Typescript deklaratsioonidest automaatselt atribuutide tabeli.
Styleguidist toetab praegu Reacti ja Vue.
Juturaamat
Storybook positsioneerib end kasutajaliidese komponentide arenduskeskkonnana. Selle asemel, et kirjutada näidiskomponente Markdowni või MDX-failidesse, kirjutage ajalugu Javascripti failide sees. Lugu dokumenteerida komponendi konkreetne olek. Näiteks võib komponendil olla laaditud oleku ja keelatud oleku ajalugu (blokeeritud).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook on palju keerulisem kui Stylegudist ja Docz. Kuid samal ajal on see kõige populaarsem variant; projektil on Githubis rohkem kui 36 000 tärni. See on avatud lähtekoodiga projekt, millel on 657 kaastöötajat ja täiskohaga töötajat. Seda kasutavad Airbnb, Algolia, Atlassian, Lyft ja Salesforce. Storybook toetab rohkem raamistikke kui konkurendid – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte ja tavaline HTML.
Tulevases versioonis on Doczi funktsioone ja MDX-i tutvustatakse.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Storybooki uued funktsioonid võetakse järgmise paari kuu jooksul järk-järgult kasutusele ja tundub, et see on suur samm edasi.
Tulemused
Mustriteegi eelised on esile tõstetud miljonites Mediumi artiklites. Kui need on hästi tehtud, hõlbustavad need seotud toodete loomist ja identiteedi säilitamist. Loomulikult ei loo ükski neist tööriistadest võluväel disainisüsteemi. See nõuab hoolikat disaini ja CSS-i. Kuid kui on aeg muuta disainisüsteem kogu ettevõttele kättesaadavaks, on Docz, Storybook ja Stylegudist suurepärased võimalused.
Tõlkija käest. See on minu esimene Habré kogemus. Kui leiate ebatäpsusi või teil on ettepanekuid artikli täiustamiseks, kirjutage mulle isikliku sõnumiga.
Allikas: www.habr.com