Lehet, hogy a legjobb nyílt forráskódú projekted van, de ha nincs jó dokumentációja, valószínű, hogy sosem fog sikerülni. Az irodában a jó dokumentáció lehetővé teszi, hogy ne kelljen ugyanazokra a kérdésekre válaszolnod. A dokumentáció biztosítja azt is, hogy az emberek megértsék a projektet, ha a kulcsfontosságú munkatársak távoznak, vagy a szerepek megváltoznak. Az élő irányelvek segítenek a befektetett adatok integritásának megőrzésében.
Ha hosszú szöveget kell írnod, a Markdown nagyszerű alternatíva a HTML-hez. Néha a Markdown szintaxisa nem elegendő. Ilyen esetben HTML-t is használhatunk benne. Például, egyedi elemeket. Tehát ha dizájnrendszert építesz natív webkomponensekkel, könnyen beillesztheted őket a szöveges dokumentációba. Ha React-ot (vagy bármilyen más JSX keretrendszert, például Preact vagy Vue) használsz, akkor ugyanazt megteheted az MDX segítségével.
Ez a cikk egy széles körű áttekintést nyújt a dokumentációs és irányelv készítő eszközökről. Nem minden itt felsorolt eszköz használ MDX-et, de egyre gyakrabban beépítik a dokumentáló eszközökbe.
Mi az MDX?
Fájl .mdx ugyanaz a szintaxis, mint a Markdowné, de lehetővé teszi interaktív JSX komponensek importálását és azok beágyazását a tartalmadba. A Vue komponensek támogatása alfa verzióban van. Ahhoz, hogy dolgozni tudj az MDX-szel, elegendő telepítened a "Create React App"-et. Vannak pluginek a Next.js-hez és Gatsby-hez is. A következő Docusaurus verzió (2-es verzió) is rendelkezni fog beépített támogatással.
Dokumentáció írása Docusaurus-szal
A Docusaurust a Facebook készítette. Minden nyílt forráskódú projektjükben használják, kivéve a React-ot. A cégen kívül a Redux, a Prettier, a Gulp és a Babel is használja.
A Docusaurust használó projektek.
A Docusaurust a dokumentáció írásához lehet használni, nemcsak a frontend leírásához. Alapját a React képezi, de ahhoz, hogy használni tudd, nem szükséges ismerned. Egyszerűen veszi a Markdown fájljaidat, egy csipetnyi varázslatot, és jól strukturált, formázott és olvasható dokumentáció készül gyönyörű dizájnnal. . Néhány kérdés teljesen elég jónak tűnik, mások pedig nem teljesítik a fent említett teszteket, különösen a "keresés egyszerűsége" ellenőrzését. A Redux weboldalán megtekinthető a Docusaurus alapértelmezett sablonja.
A Redux weboldalán meg lehet nézni a Docusaurus alapértelmezett sablonját.
A Docusaurus-szal készült weboldalak Markdown alapú blogot is tartalmazhatnak. A szintaxis kiemeléséhez a Prism.js azonnal csatlakozik. Annak ellenére, hogy a Docusaurus viszonylag nemrégiben jelent meg, 2018 legjobb eszközének ismerték el a StackShare-en.
További tartalomkészítési lehetőségek
A Docusaurus kifejezetten dokumentáció készítésére lett tervezve. Természetesen millió egy módja van egy weboldal létrehozásának — saját megoldását bármilyen nyelven, CMS-ben megvalósíthatja, vagy használhat statikus weboldal-generátort.
Például a React dokumentációja, az IBM design rendszer, az Apollo és a Ghost CMS a Gatsby-t használja — ez egy statikus weboldal-generátor, amelyet gyakran használnak blogokhoz. Ha Vue-t használ, akkor a VuePress jó választás lehet az Ön számára. Egy másik lehetőség egy Python nyelven írt generátor, a MkDocs alkalmazása. Ez nyílt forráskódú és egy YAML fájllal konfigurálható. A GitBook is egy jó opció, de csak nyílt és nem kereskedelmi csapatok számára ingyenes. Emellett egyszerűen feltöltheti a Markdown fájlokat a Git használatával, és dolgozhat velük a GitHub-on.
Komponensdokumentálás: Docz, Storybook és Styleguidist
Útmutatók, design rendszerek, komponens könyvtárak — bárhogy is nevezik őket, az utóbbi időben nagyon népszerűvé váltak. A komponens-alapú keretrendszerek, mint például a React, és a fenti eszközök megjelenése lehetővé tette számukra, hogy hiú projektekből hasznos eszközökké váljanak.
A Storybook, a Docz és a Styleguidist mind ugyanazt csinálja: interaktív elemeket jelenít meg és dokumentálja az API-jukat. Egy projekt rendelkezhet tucatnyi vagy akár több száz komponenssel — mind különböző állapotokkal és stílusokkal. Ha szeretné, hogy a komponensek újra felhasználhatóak legyenek, az embereknek tudniuk kell a létezésükről. Ehhez elegendő katalogizálni a komponenseket. Az útmutatók áttekinthető módon nyújtanak összefoglalót minden komponensről. Ez segít fenntartani a vizuális következetességet és elkerülni a megismételt 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át reprodukálni egy valós alkalmazás kontextusában. Ahelyett, hogy egy valós alkalmazásban kattintgatna, érdemes külön komponenst fejleszteni. Modellezheti a nehezen elérhető állapotokat (például a betöltési állapotot).
A különböző állapotok vizuális bemutatása és a tulajdonságlisták mellett gyakran szükséges a tartalom általános leírásának megírása — a dizájn indoklása, felhasználási esetek vagy a felhasználói tesztelési eredmények bemutatása. A Markdown tanulmányozása nagyon egyszerű — ideális esetben a irányelvek közös forrást jelentenek a tervezők és fejlesztők számára. A Docz, Styleguidist és Storybook egy egyszerű módot kínál a Markdown és a komponensek keverésére.
Docz
Jelenleg a Docz csak a React-tel működik, de aktívan dolgoznak a Preact, Vue és webkomponensek támogatásán. A Docz a legújabb a három eszköz közül, de a GitHub-on több mint 14 000 csillagot gyűjtött össze. A Docz két komponenst kínál — <Playground> és < Props >. Ezeket importálják és használják a fájlokban .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Írhatsz _markdown_-t
### Importálhatsz és használhatsz komponenseket
A saját React komponenseidet a <Playground>csomaggal is körbeölelheted, hogy hasonlót alkoss a beépített CodePen vagy CodeSandbox-hoz — így láthatod a komponensét és szerkesztheted azt.
<Props> megmutatja az összes elérhető tulajdonságot a megadott React komponenshez, 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 tartom a legkönnyebben érthetőnek és a legegyszerűbben kezelhetőnek.
Ha a Gatsby statikus weboldal-generátor rajongója vagy, a Docz kiváló integrációt kínál.
Styleguidist
A Docz-hoz hasonlóan a példák a Markdown szintaxissal íródnak. A Styleguidist Markdown kódrészleteket (három idézőjel) használ a normál .md fájlokban, nem pedig MDX-ben.
```js
A Markdown kódrészletek általában csak a kódot mutatják. A Styleguidist használatával bármely kódrészlet, amelynek nyelvi tage van js, jsx vagy javascript React komponensként jelenik meg. A Docz-hoz hasonlóan a kód szerkeszthető — megváltoztathatod a tulajdonságokat, és azonnal láthatod az eredményt.
A Styleguidist automatikusan létrehoz egy tulajdonságtáblázatot a PropTypes, Flow vagy TypeScript deklarációkból.
A Styleguidist jelenleg támogatja a React-et és a Vue-t.
Storybook
A Storybook úgy pozicionálja magát, mint az „UI komponensek fejlesztői környezete”. Ahelyett, hogy a komponensek példáit Markdown vagy MDX fájlokban írnád, a történeteket JavaScript fájlokban írod. Történet dokumentálja a komponens konkrét állapotát. Például a komponensnek lehetnek történetei a betöltési állapotról és a letiltott állapotról (letiltva).
storiesOf('Button', module)
.add('letiltva', () => (
))A Storybook sokkal összetettebb, mint a Styleguidist és Docz. Mégis, ez a legnépszerűbb választás, a projektnek több mint 36 000 csillagja van a Github-on. Ez egy nyílt forráskódú projekt, amelyben 657 résztvevő és alkalmazottak is dolgoznak. Használja az Airbnb, Algolia, Atlassian, Lyft és Salesforce. A Storybook több keretrendszert támogat, mint a versenytársak — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte és szokásos HTML.
A jövőbeli kiadásban Docz funkciók lesznek, és bevezetésre kerül az MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>A Storybook új funkciói fokozatosan fognak megjelenni a következő hónapokban, és úgy tűnik, hogy ez egy nagy lépés előre.
Összegzés
A mintakönyvtár előnyeit millió cikk dicséri a Mediumon. Amikor minden jól van megvalósítva, megkönnyítik a kapcsolódó termékek létrehozását és az identitás fenntartását. Természetesen egyik eszköz sem segít varázslatosan létrehozni egy design rendszert. Ehhez alapos tervezés és CSS szükséges. De amikor eljön az idő, hogy a design rendszer elérhető legyen az egész vállalat számára, a Docz, a Storybook és a Styleguidist nagyszerű lehetőségek.
A fordítótól. Ez az első tapasztalatom a Habrán. Ha hibákat talált, vagy javaslatai vannak a cikk javítására — írjon nekem üzenetet.
Forrás: habr.com
