Puede que tengas el 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 te permitirá no responder las mismas preguntas repetidamente. La documentación también garantiza que las personas pueden entender el proyecto si los empleados clave dejan la empresa o cambian de roles. Las guías en vivo ayudarán a asegurar la integridad de los datos.
Si necesitas escribir un texto largo, Markdown es una excelente alternativa a HTML. A veces, la sintaxis de Markdown no es suficiente. En este caso, podemos usar HTML dentro de él. Por ejemplo, elementos personalizados. Por lo tanto, si estás construyendo un sistema de diseño con componentes web nativos, es fácil incluirlos en la documentación textual. Si utilizas React (o cualquier otro marco JSX, como Preact o Vue), puedes hacer lo mismo utilizando MDX.
Este artículo es una amplia revisión de herramientas para escribir documentación y crear guías. No todas las herramientas enumeradas aquí utilizan MDX, pero cada vez se integra más en las herramientas de documentación.
¿Qué es MDX?
Archivo .mdx tiene la misma sintaxis que Markdown, pero permite importar componentes interactivos JSX y embebedarlos en tu contenido. El soporte para componentes de Vue está en alfa. Para comenzar a trabajar con MDX, basta con instalar "Create React App". Hay plugins para Next.js y Gatsby. La siguiente versión de Docusaurus (versión 2) también tendrá soporte incorporado.
Escribiendo documentación con Docusaurus
Docusaurus fue creado por Facebook. Lo utilizan en cada proyecto de código abierto, excepto en React. Fuera de la empresa, lo utilizan Redux, Prettier, Gulp y Babel.
Proyectos que utilizan Docusaurus.
Docusaurus se puede utilizar para escribir cualquier documentación, no solo para describir el frontend. Bajo el capó tiene React, pero no es necesario estar familiarizado con él para usarlo. Toma tus archivos Markdown, un toque de magia, y la documentación bien estructurada, formateada y legible con un bonito diseño está lista.
En el sitio de Redux se puede ver la plantilla estándar de Docusaurus.
Los sitios creados con Docusaurus también pueden incluir un blog basado en Markdown. Para la resaltación de sintaxis, Prism.js está integrado de inmediato. A pesar de que Docusaurus apareció relativamente recientemente, ha sido reconocido como la mejor herramienta de 2018 en StackShare.
Otras opciones para crear contenido
Docusaurus está diseñado específicamente para crear documentación. Por supuesto, hay un millón y una manera de hacer un sitio: puedes desplegar tu propia solución en cualquier lenguaje, CMS o utilizar un generador de sitios estáticos.
Por ejemplo, la documentación de React, el sistema de diseño de IBM, Apollo y Ghost CMS utilizan Gatsby, que es un generador de sitios estáticos que se usa a menudo para blogs. Si trabajas con Vue, VuePress será una buena opción para ti. Otra alternativa es usar un generador escrito en Python: MkDocs. Es de código abierto y se configura a través de un solo archivo YAML. GitBook también es una buena opción, pero es gratuito solo para equipos abiertos y no comerciales. También puedes simplemente subir archivos markdown utilizando git y trabajar con ellos en Github.
Documentación de componentes: Docz, Storybook y Styleguidist
Guías, sistemas de diseño, bibliotecas de componentes: como sea que los llames, se han vuelto muy populares últimamente. La aparición de frameworks de componentes, como React, y las herramientas mencionadas aquí, ha permitido convertirlos de proyectos vanidosos en herramientas útiles.
Storybook, Docz y Styleguidist hacen lo mismo: muestran elementos interactivos y documentan su API. Un proyecto puede tener decenas o incluso cientos de componentes, todos con diferentes estados y estilos. Si quieres que los componentes sean reutilizables, la gente debe saber que existen. Para ello, es suficiente con catalogar los componentes. Las guías proporcionan una visión general fácil de buscar de todos tus componentes. Esto ayuda a mantener la coherencia visual y evitar el trabajo repetido.
Estas herramientas ofrecen una manera conveniente de ver diferentes estados. Puede ser difícil reproducir cada estado de un componente en el contexto de una aplicación real. En lugar de hacer clic en una aplicación real, vale la pena desarrollar un componente por separado. Puedes simular estados difíciles de alcanzar (por ejemplo, el estado de carga).
Junto con la demostración visual de varios estados y una lista de propiedades, a menudo es necesario escribir una descripción general del contenido: justificación del diseño, casos de uso o descripción de los resultados de la prueba de usuario. Markdown es muy fácil de aprender; idealmente, las directrices deberían ser un recurso compartido para diseñadores y desarrolladores. Docz, Styleguidist y Storybook ofrecen una forma fácil de mezclar Markdown con componentes.
Docz
Actualmente, Docz solo funciona con React, pero se está trabajando activamente en el soporte para Preact, Vue y componentes web. Docz es la más reciente de las tres herramientas, pero ha conseguido más de 14,000 estrellas en Github. Docz presenta dos componentes: <Playground> y < Props >. Se importan y utilizan en archivos .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Puedes _escribir_ **markdown**
### Puedes importar y usar componentes
Puedes envolver tus propios componentes de React usando <Playground>, para crear una versión similar a CodePen o CodeSandbox, es decir, puedes ver tu componente y editarlo.
<Props> mostrará todas las propiedades disponibles para ese componente React, los valores predeterminados y si la propiedad es requerida.
<Props of={Button} />Personalmente, considero que este enfoque basado en MDX es el más fácil de entender y el más sencillo de trabajar.
Si eres fanático del generador de sitios estáticos Gatsby, Docz ofrece una excelente integración.
Styleguidist
Al igual que en Docz, los ejemplos se escriben utilizando la sintaxis Markdown. Styleguidist utiliza bloques de código Markdown (tres comillas) en archivos .md normales, en lugar de en MDX.
```js
Los bloques de código en Markdown generalmente solo muestran código. Al usar Styleguidist, cualquier bloque de código con la etiqueta de lenguaje js, jsx o javascript se mostrará como un componente de React. Al igual que en Docz, el código es editable: puedes cambiar propiedades y ver el resultado al instante.
Styleguidist generará automáticamente una tabla de propiedades a partir de las declaraciones de PropTypes, Flow o Typescript.
Styleguidist ahora admite React y Vue.
Storybook
Storybook se presenta como un "entorno de desarrollo de componentes UI." En lugar de escribir ejemplos de componentes dentro de archivos Markdown o MDX, escribes historias dentro de archivos Javascript. Historia documentan un estado específico del componente. Por ejemplo, un componente puede tener historias para un estado de carga y un estado deshabilitado (deshabilitado).
storiesOf('Button', module)
.add('deshabilitado', () => (
))Storybook es mucho más complicado que Styleguidist y Docz. Sin embargo, es la opción más popular, con más de 36,000 estrellas en GitHub. Este es un proyecto de código abierto, con 657 colaboradores y mantenido por personal constante. Lo utilizan Airbnb, Algolia, Atlassian, Lyft y Salesforce. Storybook admite más frameworks que sus competidores: React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte y HTML común.
En la próxima versión, se incorporarán funciones de Docz e implementará MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Las nuevas funcionalidades de Storybook se introducirán gradualmente en los próximos meses y, aparentemente, representarán un gran avance.
Resultados
Las ventajas de la biblioteca de patrones se alaban en millones de artículos en Medium. Cuando se hace bien, facilitan la creación de productos relacionados y el mantenimiento de la identidad. Por supuesto, ninguna de estas herramientas ayudará a crear mágicamente un sistema de diseño. Esto requiere un diseño de diseño y CSS cuidadoso. Pero cuando llegue el momento de hacer que el sistema de diseño esté disponible para toda la empresa, Docz, Storybook y Styleguidist son excelentes opciones.
Del traductor. Esta es mi primera experiencia en Habré. Si encuentras alguna imprecisión o tienes sugerencias para mejorar el artículo, envíame un mensaje privado.
Fuente: habr.com
