Puede tener el mejor proyecto de código abierto del mundo pero, si no tiene una buena documentación, lo más probable es que nunca despegue. En la oficina, una buena documentación podría ahorrarle tener que responder repetidamente las mismas preguntas. La documentación garantiza que las personas puedan descubrir cómo funcionan las cosas si los empleados clave deciden abandonar la empresa o cambiar de rol. Las pautas de codificación bien documentadas ayudan a brindar coherencia a una base de código.
Si está escribiendo texto de formato largo, Markdown es claramente una gran alternativa a la creación de HTML. A veces, sin embargo, la sintaxis de Markdown no es suficiente. Siempre ha sido posible escribir HTML directamente dentro de los documentos de Markdown. Esto incluye elementos personalizados, por lo que, si está creando un sistema de diseño con componentes web nativos, es fácil incorporarlos dentro de su documentación basada en texto. Si está trabajando con React (o cualquier otro marco que hable JSX, como Preact o Vue), puede hacer lo mismo usando MDX.
Este artículo es una descripción general amplia de las herramientas disponibles para escribir documentación y para crear guías de estilo. No todas las herramientas enumeradas aquí utilizan MDX, pero se está incorporando cada vez más a las herramientas de documentación.
¿Qué es MDX?
A .mdx El archivo tiene exactamente la misma sintaxis que un archivo Markdown normal, pero le permite importar componentes JSX interactivos e incrustarlos en su contenido. El soporte para los componentes de Vue está en alfa. Es fácil configurar MDX con la aplicación Create React. Hay complementos MDX para Next.js y Gatsby. El próximo lanzamiento de la versión dos de Docusaurus también vendrá con soporte incorporado.
Escribir documentación con Docusaurus
Docusaurus está hecho por Facebook y es utilizado por todos los proyectos de código abierto de Facebook, además de React. También lo utilizan muchos proyectos importantes de código abierto fuera de Facebook, incluidos Redux, Prettier, Gulp y Babel.
Proyectos haciendo uso de Docusaurus.
Puede usar Docusaurus para documentar cualquier cosa, no es específico de front-end. Docusaurus usa React bajo el capó, pero no es necesario que conozca ese marco para usarlo. Tomará sus archivos de Markdown y los convertirá en un sitio de documentación bien estructurado, bien formateado y legible, con un diseño agradable desde el primer momento.
El sitio de Redux muestra el diseño típico de Docusaurus
Los sitios creados con Docusaurus también pueden incluir un blog basado en Markdown. Prism.js se incluye de forma predeterminada para el resaltado de sintaxis de configuración cero. Si bien es relativamente nuevo, Docusaurus ha demostrado ser popular, siendo votado como el nueva herramienta número uno de 2018 en Stack Share.
Otras opciones para contenido escrito
Docusaurus atiende específicamente a la documentación de construcción. Por supuesto, hay un millón de formas de crear un sitio web, por lo que puede implementar su propia solución con cualquier lenguaje de back-end, CMS o generador de sitios estáticos.
Los sitios de documentación para React, el sistema de diseño de IBM, Apollo y Ghost CMS usan Gatsby, por ejemplo, un generador de sitios estáticos genéricos que a menudo se usa para blogs. Si trabaja con el marco Vue, VuePress se está convirtiendo en una opción popular. MkDocs es un generador de sitios estáticos de código abierto para crear documentación, escrito en Python y configurado con un único archivo YAML. GitBook es un producto pago popular que es gratuito para equipos de código abierto y sin fines de lucro. Si está creando documentación interna y quiere algo fácil, la experiencia de lectura en GitHub en sí no es tan mala, por lo que podría enviar algunos archivos de Markdown y dejarlo así.
Componentes de documentación: Docz, Storybook y Styleguidist
Las guías de estilo, los sistemas de diseño, las bibliotecas de patrones, como quiera llamarlos, se han convertido en un área de preocupación muy popular en la última década. Lo que realmente marcó la diferencia al convertirlos de proyectos de vanidad en herramientas útiles no es la pontificación de los líderes de opinión, sino la aparición de marcos de trabajo basados en componentes, como React, y las herramientas mencionadas aquí.
Storybook, Docz y Styleguidist hacen prácticamente lo mismo: muestran componentes de interfaz de usuario interactivos y documentan su API. Un proyecto puede tener docenas o incluso cientos de componentes para realizar un seguimiento, todos con una variedad de estados y estilos. Si desea que los componentes se reutilicen, la gente debe saber que existen. Ayudamos a la detección cuando catalogamos componentes. Una guía de estilo brinda una descripción general fácil de buscar y escanear de todos los componentes de la interfaz de usuario. Esto ayuda a mantener la consistencia visual y evita la duplicación de trabajo.
Estas herramientas proporcionan una manera conveniente de revisar diferentes estados. Puede ser difícil reproducir todos los estados de un componente en el contexto de una aplicación real. En lugar de tener que hacer clic en una aplicación real, puede ser útil desarrollar un componente de forma aislada. Los estados difíciles de alcanzar (como un estado de carga, por ejemplo) se pueden simular.
Dan Green escribió una buena sinopsis de los beneficios de usar Storybook, pero se aplica igualmente a Docz y Styleguidist:
“Storybook ha hecho que sea muy fácil para los diseñadores que codifican colaborar con los ingenieros. Al trabajar en un libro de cuentos, no necesitan ejecutar un entorno completo (contenedor acoplable, etc.). Para Wave, tenemos muchos componentes importantes que solo son visibles en medio de un proceso de corta duración y lento de reproducir (es decir, una pantalla de carga que solo se muestra mientras un usuario configura su cuenta de pago). Antes de Storybook, no teníamos una buena manera de trabajar en estos componentes y nos vimos obligados a realizar modificaciones temporales para hacerlos visibles. Ahora, con Storybook tenemos un lugar aislado para trabajar fácilmente en ellos, que tiene la característica adicional de ser fácilmente accesible para diseñadores y PM. También hace que sea muy fácil para nosotros mostrar estos estados en demostraciones de sprint”.
– Dan Green, Wave Financial
Además de visualizar diferentes estados uno al lado del otro y enumerar accesorios, a menudo es útil tener contenido escrito sobre un componente, ya sea que explique la justificación del diseño, los casos de uso o describa los resultados de las pruebas del usuario. Markdown es bastante fácil de aprender para cualquiera; idealmente, una guía de estilo debería ser un recurso conjunto para diseñadores y desarrolladores al que contribuyan ambas disciplinas. Docz, Styleguidist y Storybook ofrecen una manera de mezclar sin problemas Markdown con los propios componentes.
Docz
Actualmente, Docz es un proyecto exclusivo de React, pero está trabajando en la compatibilidad con Preact, Vue y componentes web. Docz es la más nueva de las tres herramientas, pero ya cuenta con más de 14 000 estrellas en GitHub. Es, en mi opinión, la solución más fácil para trabajar. Docz proporciona dos componentes: y . Estos son importados y utilizados directamente en .mdx archivos
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 de React con para crear el equivalente de un CodePen o CodeSandbox incrustado: una vista de su componente junto con el código editable.
<button>click</button> mostrará todos los accesorios disponibles para un componente de React determinado, los valores predeterminados y si el accesorio es necesario.
Personalmente, considero que este enfoque basado en MDX es el más simple de entender y el más fácil de usar.
Si eres fanático del generador de sitios estáticos basado en React Gatsby, Docz ofrece una gran integración.
guía de estilo
Al igual que con Docz, los ejemplos se escriben usando la sintaxis de Markdown. Styleguidist usa bloques de código Markdown (triples acentos graves) en forma regular .md archivos en lugar de MDX:
```js
<button> console.log('clicked')>Push Me</button>
```Los bloques de código en Markdown generalmente solo muestran el código. Con Styleguidist, cualquier bloque de código con una etiqueta de idioma de js, jsx o javascript se representará como un componente de React junto con el código. Al igual que con Docz, el código es editable: puede cambiar los accesorios y ver el resultado al instante.
Styleguidist creará automáticamente una tabla de accesorios a partir de declaraciones PropTypes, Flow o Typescript.
Styleguidist actualmente es compatible con React y Vue.
libro de cuentos
Storybook se comercializa a sí mismo como “un entorno de desarrollo para componentes de interfaz de usuario”. En lugar de escribir ejemplos de componentes dentro de archivos Markdown o MDX, escribe historias dentro de archivos Javascript. Una historia documenta un estado particular de un componente. Un componente puede tener historias para un estado de carga y un estado deshabilitado, por ejemplo.
storiesOf('Button', module)
.add('disabled', () => (
<button disabled="disabled">lorem ipsum</button>
))Storybook es menos sencillo de usar que Styleguidist y Docz. Sin embargo, con más de 36 000 estrellas de GitHub, es la opción más popular. Es un proyecto de código abierto con 657 colaboradores y un mantenedor a tiempo completo. Lo utilizan, entre otros, Airbnb, Algolia, Atlassian, Lyft y Salesforce. Storybook admite más marcos que cualquier otra oferta: React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte y HTML simple son compatibles.
Escribir documentación sobre componentes actualmente requiere complementos. En una versión futura, Storybook se inspirará en Docz y adoptará MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<button disabled="disabled">lorem ipsum</button>La nueva función de Documentos de Storybook se implementará gradualmente durante los próximos meses y parece que será un gran paso adelante.
Lo usas @storybookjs para documentos de componentes o sistemas de diseño? Te va a encantar DocBlocks:
📦 Visita MDX
🏗 Modulares y componibles
🤝 Compatible con @gatsbyjs, #nextjs, etc.
🔜 https://t.co/AmE4l9B3FU por @mshilman pic.twitter.com/Q48PQCmiEt
—Dominic Nguyen (@domyen) 28 de abril de 2019
Terminando
Los beneficios de las bibliotecas de patrones se han elogiado hasta la saciedad en un millón de artículos de Medium. Cuando se hacen bien, ayudan a la consistencia visual y facilitan la creación de productos cohesivos. Por supuesto, ninguna de estas herramientas puede crear un sistema de diseño mágico. Eso requiere una cuidadosa reflexión tanto sobre el diseño como sobre CSS. Pero cuando llega el momento de comunicar ese sistema al resto de una organización, Docz, Storybook y Styleguidist son excelentes opciones.