Sinulla voi olla paras avoimen lähdekoodin projekti, mutta jos sillä ei ole hyvää dokumentaatiota, se ei todennäköisesti koskaan käynnisty. Toimistossa hyvä dokumentaatio estää sinua vastaamasta samoihin kysymyksiin. Dokumentaatiolla varmistetaan myös, että ihmiset ymmärtävät projektin, jos avainhenkilöt lähtevät yrityksestä tai roolit vaihtuvat. Living-ohjeet auttavat varmistamaan tietojen eheyden.
Jos sinun on kirjoitettava pitkää tekstiä, Markdown on loistava vaihtoehto HTML:lle. Joskus Markdown-syntaksi ei riitä. Tässä tapauksessa voimme käyttää HTML:ää sen sisällä. Esimerkiksi mukautetut elementit. Siksi, jos rakennat suunnittelujärjestelmää alkuperäisistä verkkokomponenteista, ne voidaan helposti sisällyttää tekstidokumentaatioon. Jos käytät Reactia (tai mitä tahansa muuta JSX-kehystä, kuten Preact tai Vue), voit tehdä saman MDX:n avulla.
Tämä artikkeli on laaja katsaus työkaluihin dokumentaation kirjoittamiseen ja ohjeiden luomiseen. Kaikki tässä luetellut työkalut eivät käytä MDX:ää, mutta se sisällytetään yhä enemmän dokumentointityökaluihin.
Mikä on MDX?
tiedosto .mdx sillä on sama syntaksi kuin Markdownilla, mutta voit tuoda interaktiivisia JSX-komponentteja ja upottaa ne sisältöösi. Vue-komponenttien tuki on alfaversiossa. Aloita työskentely MDX:n kanssa asentamalla "Create React App". Next.js:lle ja Gatsbylle on laajennuksia. Docusauruksen seuraava versio (versio 2) sisältää myös alkuperäisen tuen.
Dokumentaation kirjoittaminen Docusauruksella
Docusaurus kirjoitti Facebookissa. He käyttävät sitä kaikissa avoimen lähdekoodin projekteissa paitsi Reactissa. Yrityksen ulkopuolella sitä käyttävät Redux, Prettier, Gulp ja Babel.
Projektit, jotka käyttävät Docusaurusta.
Docusaurusta voidaan käyttää kirjoittamiseen kaikki dokumentaatio, ei vain käyttöliittymän kuvaamiseen. Siinä on React konepellin alla, mutta sinun ei tarvitse tuntea sitä käyttääksesi sitä. Se vie Markdown-tiedostosi, ripaus taikuutta ja hyvin jäsennelty, muotoiltu ja luettava dokumentaatio kauniilla ulkoasulla on valmis.
Redux-verkkosivustolla voit nähdä standardin Docusaurus-mallin
Docusaurusella rakennetuilla verkkosivustoilla voi olla myös Markdown-pohjainen blogi. Prism.js yhdistetään välittömästi syntaksin korostusta varten. Huolimatta siitä, että Docusaurus ilmestyi suhteellisen äskettäin, se tunnustettiin vuoden 2018 parhaaksi työkaluksi StackSharessa.
Muut sisällönluontivaihtoehdot
Docusaurus on suunniteltu erityisesti dokumenttien luomiseen. Tietenkin on olemassa miljoona ja yksi tapa tehdä verkkosivusto - voit ottaa käyttöön oman ratkaisusi millä tahansa kielellä, sisällönhallintajärjestelmällä tai käyttää staattista sivustogeneraattoria.
Esimerkiksi Reactin, IBM:n suunnittelujärjestelmän, Apollon ja Ghost CMS:n dokumentaatiossa käytetään Gatsbyä - staattista sivustogeneraattoria, jota käytetään usein blogeissa. Jos työskentelet Vuen kanssa, VuePress on hyvä vaihtoehto sinulle. Toinen vaihtoehto on käyttää Pythonilla kirjoitettua generaattoria - MkDocs. Se on avoimen lähdekoodin ja määritetty käyttämällä yhtä YAML-tiedostoa. GitBook on myös hyvä vaihtoehto, mutta se on ilmainen vain julkisille ja ei-kaupallisille tiimeille. Voit myös yksinkertaisesti ladata mardown-tiedostoja Gitillä ja käsitellä niitä Githubissa.
Dokumentointikomponentit: Docz, Storybook ja Styleguidist
Ohjeet, järjestelmäsuunnittelu, komponenttikirjastot - kutsut niitä miksi tahansa, niistä on tullut erittäin suosittuja viime aikoina. Reactin kaltaisten komponenttikehysten ja tässä mainittujen työkalujen tulo on muuttanut ne turhamaisista projekteista hyödyllisiksi työkaluiksi.
Storybook, Docz ja Styleguidist tekevät kaikki saman asian: näyttävät interaktiivisia elementtejä ja dokumentoivat niiden API. Projektissa voi olla kymmeniä tai jopa satoja komponentteja – kaikilla eri tiloja ja tyylejä. Jos haluat, että komponentteja käytetään uudelleen, ihmisten on tiedettävä niiden olemassaolo. Voit tehdä tämän luetteloimalla komponentit. Ohjeet tarjoavat helposti löydettävän yleiskatsauksen kaikista komponenteistasi. Tämä auttaa säilyttämään visuaalisen yhtenäisyyden ja välttämään toistuvan työn.
Nämä työkalut tarjoavat kätevän tavan tarkastella eri tiloja. Voi olla vaikeaa toistaa komponentin jokaista tilaa todellisen sovelluksen yhteydessä. Varsinaisen sovelluksen klikkaamisen sijaan kannattaa kehittää erillinen komponentti. Vaikeasti saavutettavia tiloja (kuten lataustiloja) voidaan simuloida.
Eri tilojen visuaalisen esittelyn ja ominaisuuksien luettelon lisäksi on usein tarpeen kirjoittaa yleinen kuvaus sisällöstä - suunnittelun perusteet, käyttötapaukset tai kuvaukset käyttäjien testaustuloksista. Markdown on erittäin helppo oppia – ihannetapauksessa ohjeiden tulisi olla suunnittelijoiden ja kehittäjien yhteinen resurssi. Docz, Styleguidist ja Storybook tarjoavat tavan yhdistää Markdown helposti komponentteihin.
Docz
Tällä hetkellä Docz toimii vain Reactin kanssa, mutta käynnissä on aktiivinen työ Preactin, Vuen ja verkkokomponenttien tukemiseksi. Docz on uusin kolmesta työkalusta, mutta se on onnistunut keräämään yli 14 000 tähteä Githubissa. Docz esittelee kaksi komponenttia − <Playground> и < Props >. Ne tuodaan ja käytetään tiedostoissa .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Voit kääriä omat React-komponenttisi <Playground>luodaksesi analogisen sisäänrakennetusta CodePenistä tai CodeSandboxista - eli näet komponenttisi ja voit muokata sitä.
<Playground>
<Button>click</Button>
</Playground><Props> näyttää kaikki tietyn React-komponentin käytettävissä olevat ominaisuudet, oletusarvot ja vaaditaanko ominaisuus.
<Props of={Button} />Henkilökohtaisesti tämä MDX-pohjainen lähestymistapa on mielestäni helpoin ymmärtää ja helpoin työskennellä.
Jos olet Gatsbyn staattisen sivustogeneraattorin fani, Docz tarjoaa loistavan integroinnin.
Tyyliopas
Kuten Docz, esimerkit kirjoitetaan Markdown-syntaksilla. Styleguidist käyttää Markdown-koodilohkoja (kolminkertaisia lainausmerkkejä) tavallisissa tiedostoissa .md tiedostot, ei MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Markdownin koodilohkot näyttävät yleensä vain koodin. Käytettäessä Stylegudist, mikä tahansa koodilohko, jossa on kielitunniste js, jsx tai javascript hahmonnetaan React-komponenttina. Kuten Docz, koodi on muokattavissa - voit muuttaa ominaisuuksia ja nähdä heti tuloksen.
Styleguidist luo automaattisesti ominaisuustaulukon PropTypes-, Flow- tai Typescript-ilmoituksista.
Styleguidist tukee tällä hetkellä Reactia ja Vuea.
Satukirja
Storybook asettuu "käyttöliittymäkomponenttien kehitysympäristöksi". Sen sijaan, että kirjoittaisit esimerkkikomponentteja Markdown- tai MDX-tiedostoihin, kirjoitat historia Javascript-tiedostojen sisällä. Tarina dokumentoi komponentin tietty tila. Esimerkiksi komponentilla voi olla historiat ladatusta tilasta ja pois käytöstä (vammaiset).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook on paljon monimutkaisempi kuin Stylegudist ja Docz. Mutta samaan aikaan tämä on suosituin vaihtoehto; projektilla on yli 36 000 tähteä Githubissa. Se on avoimen lähdekoodin projekti, jossa on 657 avustajaa ja kokopäiväistä henkilökuntaa. Sitä käyttävät Airbnb, Algolia, Atlassian, Lyft ja Salesforce. Storybook tukee enemmän kehyksiä kuin kilpailijat - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte ja tavallinen HTML.
Tulevassa julkaisussa on Doczin ominaisuuksia ja MDX otetaan käyttöön.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Storybookin uudet ominaisuudet otetaan käyttöön asteittain seuraavien kuukausien aikana, ja näyttää siltä, että se on iso askel eteenpäin.
Tulokset
Kuviokirjaston etuja ylistetään miljoonissa Mediumin artikkeleissa. Hyvin tehtynä ne helpottavat vastaavien tuotteiden luomista ja identiteetin ylläpitämistä. Tietenkään mikään näistä työkaluista ei luo taianomaisesti suunnittelujärjestelmää. Tämä vaatii huolellista suunnittelua ja CSS:ää. Mutta kun on aika tehdä suunnittelujärjestelmästä koko yrityksen käytettävissä, Docz, Storybook ja Styleguidist ovat loistavia vaihtoehtoja.
Kääntäjältä. Tämä on ensimmäinen kokemukseni Habresta. Jos löydät epätarkkuuksia tai sinulla on ehdotuksia artikkelin parantamiseksi, kirjoita minulle henkilökohtaisesti.
Lähde: will.com