Puedes tener el mejor proyecto de código abierto, pero si no tiene buena documentación, es probable que nunca despegue. En la oficina, una buena documentación evitará que respondas las mismas preguntas. La documentación también garantiza que las personas puedan comprender el proyecto si los empleados clave abandonan la empresa o cambian los roles. Las pautas vivas ayudarán a garantizar la integridad de los datos.
Si necesita escribir texto extenso, Markdown es una excelente alternativa al HTML. A veces, la sintaxis de Markdown no es suficiente. En este caso podemos usar HTML dentro del mismo. Por ejemplo, elementos personalizados. Por lo tanto, si está creando un sistema de diseño con componentes web nativos, pueden incluirse fácilmente en la documentación de texto. Si estás usando React (o cualquier otro marco JSX como Preact o Vue), puedes hacer lo mismo usando MDX.
Este artículo es una descripción general amplia de las herramientas para escribir documentación y crear pautas. No todas las herramientas enumeradas aquí utilizan MDX, pero cada vez se incluye más en las herramientas de documentación.
¿Qué es MDX?
Expediente .mdx tiene la misma sintaxis que Markdown, pero le permite importar componentes JSX interactivos e incrustarlos en su contenido. La compatibilidad con los componentes de Vue está en alfa. Para comenzar a trabajar con MDX, simplemente instale "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 nativo.
Escribir documentación con Docusaurus
Docusaurus escribió en Facebook. Lo usan en todos los proyectos 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 sólo para describir la interfaz. Tiene React bajo el capó, pero no es necesario estar familiarizado con él para usarlo. Se necesitan sus archivos Markdown, una pizca de magia y la documentación bien estructurada, formateada y legible con un hermoso diseño está lista.
En el sitio web de Redux puedes ver la plantilla estándar de Docusaurus
Los sitios web creados con Docusaurus también pueden incluir un blog basado en Markdown. Prism.js se conecta inmediatamente para resaltar la sintaxis. A pesar de que Docusaurus apareció hace relativamente poco tiempo, fue reconocida como la mejor herramienta de 2018 en StackShare.
Otras opciones de creación de contenido
Docusaurus está diseñado específicamente para crear documentación. Por supuesto, hay millones de formas de crear un sitio web: puede implementar su propia solución en cualquier idioma, CMS o utilizar un generador de sitios estáticos.
Por ejemplo, la documentación para React, el sistema de diseño de IBM, Apollo y Ghost CMS utilizan Gatsby, un generador de sitios estáticos que se utiliza a menudo para blogs. Si trabaja con Vue, VuePress es una buena opción para usted. Otra opción es utilizar un generador escrito en Python: MkDocs. Es de código abierto y se configura mediante un único archivo YAML. GitBook también es una buena opción, pero sólo es gratuito para equipos públicos y no comerciales. También puedes simplemente cargar archivos Mardown usando Git y trabajar con ellos en Github.
Componentes de documentación: Docz, Storybook y Styleguidist
Directrices, diseño de sistemas, bibliotecas de componentes: como quiera que los llame, se ha vuelto muy popular últimamente. La llegada de marcos de componentes como React y las herramientas mencionadas aquí los ha transformado de proyectos vanidosos a herramientas útiles.
Storybook, Docz y Styleguidist hacen lo mismo: mostrar elementos interactivos y documentar su API. Un proyecto puede tener docenas o incluso cientos de componentes, todos con diferentes estados y estilos. Si desea reutilizar componentes, la gente necesita saber que existen. Para ello, simplemente catalogue los componentes. Las pautas proporcionan una descripción general fácil de encontrar de todos sus componentes. Esto ayuda a mantener la coherencia visual y evitar el trabajo repetitivo.
Estas herramientas proporcionan una manera conveniente de ver diferentes estados. Puede resultar difícil reproducir cada estado de un componente en el contexto de una aplicación real. En lugar de hacer clic en la aplicación real, vale la pena desarrollar un componente independiente. Se pueden simular estados de difícil acceso (como estados de carga).
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: fundamentos del diseño, casos de uso o descripciones de los resultados de las pruebas de los usuarios. 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 forma de combinar fácilmente Markdown con componentes.
Docz
Actualmente, Docz solo funciona con React, pero se está trabajando activamente para admitir Preact, Vue y componentes web. Docz es la más reciente de las tres herramientas, pero ha logrado recopilar más de 14 estrellas en Github. Docz presenta dos componentes: <Playground> и < Props >. Se importan y utilizan 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>Puedes envolver tus propios componentes de React con <Playground>para crear un análogo del CodePen o CodeSandbox integrado, es decir, verá su componente y podrá editarlo.
<Playground>
<Button>click</Button>
</Playground><Props> mostrará todas las propiedades disponibles para un componente de React determinado, los valores predeterminados y si la propiedad es obligatoria.
<Props of={Button} />Personalmente, considero que este enfoque basado en MDX es el más fácil de entender y con el que es más fácil trabajar.
Si eres fanático del generador de sitios estáticos Gatsby, Docz ofrece una excelente integración.
Guidista de estilo
Al igual que Docz, los ejemplos se escriben utilizando la sintaxis Markdown. Styleguidist usa bloques de código Markdown (comillas triples) en archivos normales .md archivos, no MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Los bloques de código en Markdown generalmente solo muestran código. Al usar Styleguidist, cualquier bloque de código con una etiqueta de idioma js, jsx o javascript se representará como un componente de React. Al igual que 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 actualmente admite React y Vue.
Libro de cuentos
Storybook se posiciona como un "entorno de desarrollo de componentes de interfaz de usuario". En lugar de escribir componentes de ejemplo dentro de archivos Markdown o MDX, escribe historias dentro de archivos Javascript. historia documentar el estado específico de un componente. Por ejemplo, un componente puede tener historiales para un estado cargado y un estado deshabilitado (discapacitados).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook es mucho más complejo que Styleguidist y Docz. Pero al mismo tiempo, esta es la opción más popular, el proyecto tiene más de 36 estrellas en Github. Es un proyecto de código abierto con 000 contribuyentes y personal de tiempo completo. Lo utilizan Airbnb, Algolia, Atlassian, Lyft y Salesforce. Storybook admite más marcos que la competencia: React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte y HTML normal.
En una versión futura se introducirán funciones de Docz y MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Las nuevas funciones de Storybook se implementarán gradualmente durante los próximos meses y parece que será un gran paso adelante.
resultados
Los beneficios de una biblioteca de patrones se exaltan en millones de artículos en Medium. Cuando se hacen bien, facilitan la creación de productos relacionados y el mantenimiento de la identidad. Por supuesto, ninguna de estas herramientas creará mágicamente un sistema de diseño. Esto requiere un diseño cuidadoso y CSS. Pero cuando llega el momento de hacer que un sistema de diseño sea accesible para toda la empresa, Docz, Storybook y Styleguidist son excelentes opciones.
Del traductor. Esta es mi primera experiencia con Habré. Si encuentra alguna inexactitud o tiene sugerencias para mejorar el artículo, escríbame en un mensaje personal.
Fuente: habr.com