Es posible que tenga un mejor proyecto de c贸digo abierto, pero si no tiene una buena documentaci贸n, es probable que nunca despegue. En la oficina, una buena documentaci贸n le permitir谩 no responder las mismas preguntas. La documentaci贸n tambi茅n garantiza que las personas puedan comprender el proyecto si los empleados clave abandonan la empresa o si cambian los roles. Las pautas en vivo ayudan a garantizar la integridad de los datos.
Si necesita escribir texto largo, Markdown es una gran alternativa al HTML. A veces, la sintaxis de Markdown no es suficiente. En este caso, podemos usar el HTML que contiene. Por ejemplo, elementos personalizados. Por lo tanto, si est谩 creando un sistema de dise帽o con componentes web nativos, son f谩ciles de incluir en la documentaci贸n de texto. Si usa React (o cualquier otro marco JSX como Preact o Vue), puede hacer lo mismo con MDX.
Este art铆culo es una descripci贸n general de la escritura de documentaci贸n y herramientas de gu铆a. No todas las herramientas enumeradas aqu铆 usan MDX, pero cada vez se incluyen m谩s en las herramientas de documentaci贸n.
驴Qu茅 es el MDX?
El archivo .mdx tiene la misma sintaxis que Markdown, pero le permite importar componentes interactivos JSX e incrustarlos en su contenido. El soporte para componentes Vue est谩 en alfa. Para comenzar a trabajar con MDX, simplemente instale la "Crear aplicaci贸n React". Hay complementos para Next.js y Gatsby. La pr贸xima versi贸n de Docusaurus (versi贸n 2) tambi茅n tendr谩 soporte incorporado.
Escribir documentaci贸n con Docusaurus
Docusaurus escribi贸 en Facebook. Lo usan en todos los proyectos de c贸digo abierto, excepto React. Fuera de la empresa, Redux, Prettier, Gulp y Babel lo usan.
Proyectos que usan Docusaurus.
Docusaurus se puede usar para escribir cualquier documentaci贸n, no solo para describir la interfaz. Tiene React debajo de su capucha, pero para usarlo, no es necesario estar familiarizado con 茅l. Toma sus archivos Markdown, una pizca de magia y documentaci贸n bien estructurada, formateada y legible con un hermoso dise帽o listo.
En el sitio web de Redux puede ver la plantilla est谩ndar de Docusaurus
Los sitios creados con Docusaurus tambi茅n pueden incluir un blog basado en Markdown. Prism.js se conecta inmediatamente al resaltado de sintaxis. A pesar de que Docusaurus apareci贸 hace relativamente poco tiempo, fue reconocido como la mejor herramienta de 2018 en StackShare.
Otras opciones de creaci贸n de contenido
Docusaurus est谩 espec铆ficamente dise帽ado para crear documentaci贸n. Por supuesto, hay un mill贸n y una forma de crear un sitio: puede implementar su propia soluci贸n en cualquier lenguaje, CMS o utilizar el generador de sitio est谩tico.
Por ejemplo, la documentaci贸n para React, el sistema de dise帽o de IBM, Apollo y Ghost CMS usa Gatsby, un generador de sitio est谩tico que a menudo se usa para blogs. Si trabaja con Vue, entonces VuePress es una buena opci贸n para usted. Otra opci贸n es usar un generador escrito en Python - MkDocs. Es abierto y configurable con un solo archivo YAML. GitBook tambi茅n es una buena opci贸n, pero es gratis solo para equipos abiertos y sin fines de lucro. Y simplemente puede cargar archivos de Mardown usando gith y trabajar con ellos en Github.
Documentaci贸n de componentes: Docz, Storybook y Styleguidist
Pautas, dise帽o del sistema, bibliotecas de componentes, como las llame, pero se ha vuelto muy popular 煤ltimamente. El advenimiento de los marcos de componentes, como React y las herramientas mencionadas aqu铆, han hecho posible convertirlos de proyectos engre铆dos en herramientas 煤tiles.
Storybook, Docz y Styleguidist: haga lo mismo: muestre elementos interactivos y documente su API. Un proyecto puede tener docenas o incluso cientos de componentes, todos con diferentes estados y estilos. Si desea que los componentes se reutilicen, las personas deben saber que existen. Para hacer esto, simplemente catalogue los componentes. Las pautas proporcionan una visi贸n general de b煤squeda de todos sus componentes. Esto ayuda a mantener la consistencia visual y evitar el trabajo repetitivo.
Estas herramientas proporcionan una forma conveniente de ver varios estados. Puede ser dif铆cil reproducir cada estado de componente en el contexto de una aplicaci贸n real. En lugar de hacer clic en una aplicaci贸n real, debe desarrollar un componente separado. Puede simular estados dif铆ciles de alcanzar (por ejemplo, estado de arranque).
Junto con una demostraci贸n visual de varios estados y una lista de propiedades, a menudo es necesario escribir una descripci贸n general del contenido: justificaci贸n para el dise帽o, estudios de caso o descripci贸n de los resultados de las pruebas del usuario. Markdown es muy f谩cil de aprender: idealmente, las pautas deber铆an ser un recurso compartido para dise帽adores y desarrolladores. Docz, Styleguidist y Storybook ofrecen una manera de mezclar f谩cilmente Markdown con componentes.
Docz
Ahora Docz solo funciona con React, pero hay un trabajo activo en soporte para Preact, Vue y componentes web. Docz es el m谩s nuevo de los tres instrumentos, pero en Github pudo recoger m谩s de 14,000 estrellas. Docz representa dos componentes: <Playground> y < Props > . Se importan y se usan en archivos .mdx .
import { Playground, Props } from "docz"; import Button from "../src/Button"; ## You can _write_ **markdown** ### You can import and use components <Button>click</Button>
Puede envolver sus propios componentes React con <Playground> para crear un an谩logo del CodePen o CodeSandbox incorporado; es decir, ver谩 su componente y podr谩 editarlo.
<Playground> <Button>click</Button> </Playground>
<Props> mostrar谩 todas las propiedades disponibles para este componente React, los valores predeterminados y si se requiere una propiedad.
<Props of={Button} />
Personalmente, creo que este enfoque basado en MDX es el m谩s f谩cil de entender y el m谩s f谩cil de trabajar.
Si eres fan谩tico del generador de sitios est谩ticos Gatsby, Docz ofrece una gran integraci贸n.
Styleguidist
Al igual que Docz, los ejemplos se escriben usando la sintaxis de Markdown. Styleguidist utiliza bloques de c贸digo Markdown (comillas triples) en archivos .md normales, no en MDX.
```js <Button onClick={() => console.log('clicked')>Push Me</Button>
Los bloques de c贸digo en Markdown generalmente solo muestran el c贸digo. Al usar Styleguidist, cualquier bloque de c贸digo con una etiqueta de idioma js , jsx o javascript se mostrar谩 como un componente React. Al igual que en Docz, el c贸digo es editable: puede cambiar las propiedades y ver el resultado al instante.
Styleguidist crear谩 autom谩ticamente una tabla de propiedades a partir de declaraciones PropTypes, Flow o Typecript.
Styleguidist ahora es compatible con React y Vue.
Libro de cuentos
Storybook se posiciona como un "entorno de desarrollo para componentes de UI". En lugar de escribir ejemplos de componentes dentro de archivos Markdown o MDX, usted escribe historias dentro de archivos Javascript. La historia est谩 documentada por el estado espec铆fico del componente. Por ejemplo, un componente puede tener historiales para el estado de arranque y el estado deshabilitado.
storiesOf('Button', module) .add('disabled', () => ( <Button disabled>lorem ipsum</Button> ))
Storybook es mucho m谩s complicado que Styleguidist y Docz. Pero al mismo tiempo, esta es la opci贸n m谩s popular, en Github el proyecto tiene m谩s de 36,000 estrellas. Este es un proyecto de c贸digo abierto, involucra a 657 participantes y est谩 acompa帽ado por empleados de tiempo completo. Es utilizado por Airbnb, Algolia, Atlassian, Lyft y Salesforce. Storybook admite m谩s marcos que sus competidores: React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte y HTML normal.
En un lanzamiento futuro, habr谩 chips de Docz y se introducir谩 MDX.
# Button Some _notes_ about your button written with **markdown syntax**. <Story name="disabled"> <Button disabled>lorem ipsum</Button> </Story>
Las nuevas caracter铆sticas del Storybook aparecer谩n gradualmente en los pr贸ximos meses, y aparentemente este ser谩 un gran paso adelante.
Resumen
Los beneficios de la biblioteca de patrones se exaltan en millones de art铆culos en Medium. Cuando se hace bien, facilitan la creaci贸n de productos relacionados y mantienen la identidad. Por supuesto, ninguna de estas herramientas crear谩 m谩gicamente un sistema de dise帽o. Esto requiere un dise帽o cuidadoso y un dise帽o CSS. Pero cuando llega el momento de poner el sistema de dise帽o a disposici贸n de toda la empresa, Docz, Storybook y Styleguidist son excelentes opciones.
Del traductor. Esta es mi primera experiencia en Habr茅. Si encuentra que algunos no son precisos, o tiene sugerencias para mejorar el art铆culo, escriba un mensaje personal.