Lehet a legjobb nyílt forráskódú projekt, de ha nem rendelkezik megfelelő dokumentációval, akkor valószínűleg soha nem fog beindulni. Az irodában a megfelelő dokumentáció megakadályozza, hogy ugyanazokra a kérdésekre válaszoljon. A dokumentáció azt is biztosítja, hogy az emberek megértsék a projektet, ha a kulcsfontosságú alkalmazottak elhagyják a vállalatot vagy a szerepek megváltoznak. Az élő irányelvek segítenek az adatok integritásának biztosításában.
Ha hosszú szöveget kell írnia, a Markdown nagyszerű alternatívája a HTML-nek. Néha a Markdown szintaxis nem elegendő. Ebben az esetben használhatunk benne HTML-t. Például egyéni elemek. Ezért, ha natív webes összetevőket tartalmazó tervezőrendszert épít, akkor ezek könnyen beilleszthetők a szöveges dokumentációba. Ha Reactot (vagy bármely más JSX keretrendszert, például Preactot vagy Vue-t) használ, ugyanezt megteheti az MDX használatával.
Ez a cikk átfogó áttekintést nyújt a dokumentációíráshoz és az irányelvek létrehozásához szükséges eszközökről. Az itt felsorolt eszközök közül nem mindegyik használ MDX-et, de egyre gyakrabban szerepel a dokumentációs eszközökben.
Mi az MDX?
fájl .mdx szintaxisa megegyezik a Markdownéval, de lehetővé teszi interaktív JSX-összetevők importálását és beágyazását a tartalomba. A Vue összetevőinek támogatása alfa verzióban érhető el. Az MDX-szel való munka megkezdéséhez egyszerűen telepítse a „React App létrehozása” lehetőséget. Vannak bővítmények a Next.js és a Gatsby számára. A Docusaurus következő verziója (2. verzió) szintén natív támogatással fog rendelkezni.
Dokumentáció írása Docusaurusszal
– írta a Docusaurus a Facebookon. A React kivételével minden nyílt forráskódú projektben használják. A cégen kívül a Redux, a Prettier, a Gulp és a Babel használja.
Docusaurust használó projektek.
A Docusaurus használható írásra bármilyen dokumentációt, nem csak a frontend leírására. A motorháztető alatt React van, de nem kell ismerned a használatához. Szükség van a Markdown-fájlokra, egy csipetnyi varázslat és a jól strukturált, formázott és olvasható, gyönyörű dizájnú dokumentáció készen áll.
A Redux webhelyén láthatja a szabványos Docusaurus sablont
A Docusaurus segítségével készített webhelyek Markdown-alapú blogot is tartalmazhatnak. A Prism.js azonnal csatlakozik a szintaxis kiemeléséhez. Annak ellenére, hogy a Docusaurus viszonylag nemrég jelent meg, a StackShare-en 2018 legjobb eszközeként ismerték el.
Egyéb tartalomkészítési lehetőségek
A Docusaurus kifejezetten dokumentációk létrehozására készült. Természetesen millió és egy módja van a weboldal készítésének – bármilyen nyelven telepítheti saját megoldását, CMS-t, vagy használhat statikus webhelygenerátort.
Például a React, az IBM tervezési rendszer, az Apollo és a Ghost CMS dokumentációja a Gatsbyt használja – egy statikus webhelygenerátort, amelyet gyakran használnak blogokhoz. Ha a Vue-val dolgozik, akkor a VuePress jó választás az Ön számára. Egy másik lehetőség egy Python - MkDocs -ban írt generátor használata. Nyílt forráskódú, és egyetlen YAML-fájl használatával van konfigurálva. A GitBook szintén jó lehetőség, de csak nyilvános és nem kereskedelmi csapatok számára ingyenes. Egyszerűen feltölthet mardown fájlokat a Git segítségével, és dolgozhat velük a Githubban.
Dokumentáló komponensek: Docz, Storybook és Stylegudist
Irányelvek, rendszertervezés, komponenskönyvtárak – bárminek is nevezzük őket, az utóbbi időben nagyon népszerűvé vált. Az olyan összetevő-keretrendszerek megjelenése, mint a React és az itt említett eszközök, a hiábavaló projektekből hasznos eszközökké változtatta őket.
A Storybook, a Docz és a Stylegudist ugyanazt csinálja: interaktív elemeket jelenít meg, és dokumentálja az API-jukat. Egy projekt több tucat vagy akár több száz összetevőből állhat – mindegyik különböző állapotú és stílusú. Ha azt szeretné, hogy az alkatrészeket újra felhasználják, az embereknek tudniuk kell, hogy léteznek. Ehhez egyszerűen katalogizálja az alkatrészeket. Az útmutatók könnyen áttekinthető áttekintést nyújtanak az összes összetevőről. Ez segít megőrizni a vizuális konzisztenciát és elkerülni az ismétlődő munkát.
Ezek az eszközök kényelmes módot biztosítanak a különböző állapotok megtekintésére. Nehéz lehet egy komponens minden állapotának reprodukálása egy valós alkalmazás kontextusában. A tényleges alkalmazásra való kattintás helyett érdemes külön komponenst fejleszteni. A nehezen elérhető állapotok (például betöltési állapotok) szimulálhatók.
A különféle állapotok vizuális bemutatása és a tulajdonságok listája mellett gyakran szükség van a tartalom általános leírásának megírására - tervezési indokok, használati esetek vagy a felhasználói tesztelési eredmények leírása. A Markdown nagyon könnyen elsajátítható – ideális esetben az útmutatóknak a tervezők és a fejlesztők megosztott forrásai lehetnek. A Docz, a Stylegudist és a Storybook lehetőséget kínál a Markdown és az összetevők egyszerű keverésére.
Docz
Jelenleg a Docz csak a Reacttel működik, de aktív munka folyik a Preact, a Vue és a webes összetevők támogatásán. A három eszköz közül a Docz a legújabb, de több mint 14 000 csillagot sikerült összegyűjtenie a Githubon. Docz két komponenst vezet be − <Playground> и < Props >. Ezeket importálják és fájlokban használják .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Becsomagolhatja saját React komponenseit <Playground>a beépített CodePen vagy CodeSandbox analógjának létrehozásához - vagyis látja az összetevőjét és szerkesztheti azt.
<Playground>
<Button>click</Button>
</Playground><Props> megjeleníti az adott React komponens összes elérhető tulajdonságát, az alapértelmezett értékeket és azt, hogy a tulajdonság szükséges-e.
<Props of={Button} />Személy szerint ezt az MDX-alapú megközelítést a legkönnyebben érthetőnek és a legkönnyebben használhatónak találom.
Ha Ön a Gatsby statikus webhelygenerátor rajongója, a Docz nagyszerű integrációt kínál.
Stílus útmutató
A Doczhoz hasonlóan a példákat is Markdown szintaxissal írjuk. A Stylegudist a Markdown kódblokkokat (hármas idézőjelek) használja a normál fájlokban .md fájlok, nem MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>A Markdown kódblokkjai általában csak kódot mutatnak. A Stylegudist használatakor bármely nyelvi címkével ellátott kódblokk js, jsx vagy javascript React komponensként jelenik meg. A Doczhoz hasonlóan a kód szerkeszthető - megváltoztathatja a tulajdonságokat, és azonnal láthatja az eredményt.
A Styleguidist automatikusan létrehoz egy tulajdonságtáblázatot PropTypes, Flow vagy Typescript deklarációkból.
A Stylegudist jelenleg támogatja a Reactet és a Vue-t.
mesekönyv
A Storybook „UI-komponens-fejlesztő környezetként” pozícionálja magát. Ahelyett, hogy példaösszetevőket írna a Markdown- vagy MDX-fájlokba, írjon történetek Javascript fájlok belsejében. Történet dokumentálja egy komponens konkrét állapotát. Például egy komponens előzményekkel rendelkezhet egy betöltött állapothoz és egy letiltott állapothoz (Tiltva).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))A Storybook sokkal összetettebb, mint a Stylegudist és a Docz. Ugyanakkor ez a legnépszerűbb lehetőség; a projektnek több mint 36 000 csillaga van a Githubon. Ez egy nyílt forráskódú projekt 657 közreműködővel és teljes munkaidős alkalmazottal. Az Airbnb, az Algolia, az Atlassian, a Lyft és a Salesforce használja. A Storybook több keretrendszert támogat, mint a versenytársak – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte és normál HTML.
Egy jövőbeli kiadásban a Docz és az MDX szolgáltatásai is megjelennek majd.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>A Storybook új funkciói az elkövetkező néhány hónapban fokozatosan fognak megjelenni, és úgy tűnik, ez nagy előrelépés lesz.
Eredményei
A mintakönyvtár előnyeit a Médiumról szóló cikkek milliói emelik ki. Ha jól csinálják, könnyebbé teszik a kapcsolódó termékek létrehozását és az identitás fenntartását. Természetesen ezen eszközök egyike sem hoz létre varázslatos tervezési rendszert. Ez gondos tervezést és CSS-t igényel. De amikor eljön az ideje, hogy a tervezési rendszert az egész vállalat számára elérhetővé tegyük, a Docz, a Storybook és a Styleguidist remek választás.
A fordítótól. Ez az első élményem Habréval kapcsolatban. Ha bármilyen pontatlanságot talál, vagy javaslata van a cikk javítására, írjon nekem személyes üzenetben.
Forrás: will.com