Pots tenir el millor projecte de codi obert, però si no té una bona documentació, és probable que no surti mai. A l'oficina, una bona documentació impedirà respondre les mateixes preguntes. La documentació també garanteix que la gent pugui entendre el projecte si els empleats clau deixen l'empresa o canvien els rols. Les directrius de vida ajudaran a garantir la integritat de les dades.
Si necessiteu escriure text llarg, Markdown és una bona alternativa a HTML. De vegades, la sintaxi de Markdown no és suficient. En aquest cas podem utilitzar HTML dins d'ell. Per exemple, elements personalitzats. Per tant, si esteu construint un sistema de disseny amb components web nadius, es poden incloure fàcilment a la documentació de text. Si utilitzeu React (o qualsevol altre marc JSX com Preact o Vue), podeu fer el mateix amb MDX.
Aquest article és una visió general àmplia de les eines per escriure documentació i crear directrius. No totes les eines enumerades aquí utilitzen MDX, però cada cop s'inclou més a les eines de documentació.
Què és MDX?
expedient .mdx té la mateixa sintaxi que Markdown, però us permet importar components JSX interactius i incrustar-los al vostre contingut. El suport per als components Vue està en alfa. Per començar a treballar amb MDX, només cal que instal·leu "Crea l'aplicació React". Hi ha connectors per a Next.js i Gatsby. La propera versió de Docusaurus (versió 2) també tindrà suport natiu.
Redacció de documentació amb Docusaurus
Docusaurus va escriure a Facebook. L'utilitzen en tots els projectes de codi obert excepte React. Fora de l'empresa l'utilitzen Redux, Prettier, Gulp i Babel.
Projectes que utilitzen Docusaurus.
Docusaurus es pot utilitzar per escriure qualsevol documentació, no només per descriure la interfície. Té React sota el capó, però no cal que estigueu familiaritzat amb ell per utilitzar-lo. Pren els vostres fitxers Markdown, una mica de màgia i una documentació ben estructurada, formatada i llegible amb un disseny preciós està a punt.
Al lloc web de Redux podeu veure la plantilla estàndard de Docusaurus
Els llocs web creats amb Docusaurus també poden incloure un bloc basat en Markdown. Prism.js es connecta immediatament per ressaltar la sintaxi. Tot i que Docusaurus va aparèixer relativament recentment, va ser reconeguda com la millor eina del 2018 a StackShare.
Altres opcions de creació de contingut
Docusaurus està dissenyat específicament per crear documentació. Per descomptat, hi ha un milió i una de maneres de fer un lloc web: podeu implementar la vostra pròpia solució en qualsevol idioma, CMS o utilitzar un generador de llocs estàtic.
Per exemple, la documentació de React, el sistema de disseny d'IBM, Apollo i Ghost CMS utilitzen Gatsby, un generador de llocs estàtic que s'utilitza sovint per als blocs. Si treballeu amb Vue, llavors VuePress és una bona opció per a vosaltres. Una altra opció és utilitzar un generador escrit en Python - MkDocs. És de codi obert i es configura amb un sol fitxer YAML. GitBook també és una bona opció, però només és gratuït per a equips públics i no comercials. També podeu simplement carregar fitxers de mardown amb Git i treballar-hi a Github.
Components de documentació: Docz, Storybook i Styleguidist
Directrius, disseny de sistemes, biblioteques de components, sigui com els digueu, s'ha tornat molt popular últimament. L'arribada de marcs de components com React i les eines esmentades aquí els han transformat de projectes vanitat en eines útils.
Storybook, Docz i Styleguidist fan el mateix: mostren elements interactius i documenten la seva API. Un projecte pot tenir desenes o fins i tot centenars de components, tots amb diferents estats i estils. Si voleu que els components es reutilitzin, la gent ha de saber que existeixen. Per fer-ho, només cal catalogar els components. Les directrius proporcionen una visió general fàcil de trobar de tots els vostres components. Això ajuda a mantenir la consistència visual i evitar el treball repetitiu.
Aquestes eines proporcionen una manera convenient de veure diferents estats. Pot ser difícil reproduir cada estat d'un component en el context d'una aplicació real. En lloc de fer clic a l'aplicació real, val la pena desenvolupar un component separat. Es poden simular estats de difícil accés (com ara els estats de càrrega).
Juntament amb una demostració visual de diversos estats i una llista de propietats, sovint és necessari escriure una descripció general del contingut: justificacions del disseny, casos d'ús o descripcions dels resultats de les proves d'usuari. Markdown és molt fàcil d'aprendre; idealment, les directrius haurien de ser un recurs compartit per a dissenyadors i desenvolupadors. Docz, Styleguidist i Storybook ofereixen una manera de barrejar fàcilment Markdown amb components.
Docz
Actualment Docz només funciona amb React, però s'està treballant actiu per donar suport a Preact, Vue i components web. Docz és la més recent de les tres eines, però ha aconseguit recollir més de 14 estrelles a Github. Docz introdueix dos components − <Playground> и < Props >. S'importen i s'utilitzen en fitxers .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Podeu embolicar els vostres propis components React <Playground>per crear un anàleg del CodePen o CodeSandbox integrat, és a dir, veureu el vostre component i el podeu editar.
<Playground>
<Button>click</Button>
</Playground><Props> mostrarà totes les propietats disponibles per a un component de React determinat, els valors predeterminats i si la propietat és necessària.
<Props of={Button} />Personalment, trobo que aquest enfocament basat en MDX és el més fàcil d'entendre i el més fàcil de treballar.
Si sou un fan del generador de llocs estàtic Gatsby, Docz ofereix una gran integració.
Guia d'estil
Igual que Docz, els exemples s'escriuen utilitzant la sintaxi de Markdown. Styleguidist utilitza blocs de codi Markdown (cometes triples) als fitxers normals .md fitxers, no MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Els blocs de codi a Markdown normalment només mostren codi. Quan utilitzeu Styleguidist, qualsevol bloc de codi amb una etiqueta d'idioma js, jsx o javascript es representarà com a component React. Igual que Docz, el codi és editable: podeu canviar les propietats i veure el resultat a l'instant.
Styleguidist crearà automàticament una taula de propietats a partir de declaracions PropTypes, Flow o Typescript.
Styleguidist actualment és compatible amb React i Vue.
Llibre de contes
Storybook es posiciona com un "entorn de desenvolupament de components d'IU". En lloc d'escriure components d'exemple dins dels fitxers Markdown o MDX, escriviu història dins dels fitxers Javascript. Història documentar l'estat específic d'un component. Per exemple, un component pot tenir historials per a un estat carregat i un estat desactivat (discapacitat).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))El llibre de contes és molt més complex que Styleguidist i Docz. Però al mateix temps, aquesta és l'opció més popular; el projecte té més de 36 estrelles a Github. És un projecte de codi obert amb 000 col·laboradors i personal a temps complet. L'utilitzen Airbnb, Algolia, Atlassian, Lyft i Salesforce. Storybook admet més marcs que els competidors: React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte i HTML normal.
En una versió futura hi haurà funcions de Docz i s'introduiran MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Les noves funcions de Storybook es desplegaran gradualment durant els propers mesos i sembla que serà un gran pas endavant.
Resultats de
Els avantatges d'una biblioteca de patrons s'exalten en milions d'articles a Medium. Quan es fan bé, faciliten la creació de productes relacionats i el manteniment de la identitat. Per descomptat, cap d'aquestes eines crearà màgicament un sistema de disseny. Això requereix un disseny acurat i CSS. Però quan arriba el moment de fer accessible un sistema de disseny per a tota l'empresa, Docz, Storybook i Styleguidist són bones opcions.
Del traductor. Aquesta és la meva primera experiència a Habré. Si trobeu alguna inexactitud o teniu suggeriments per millorar l'article, escriu-me en un missatge personal.
Font: www.habr.com