Podes ter o mellor proxecto de código aberto, pero se non ten boa documentación, é probable que nunca despegue. Na oficina, unha boa documentación impedirá que respondas ás mesmas preguntas. A documentación tamén garante que as persoas poidan comprender o proxecto se os empregados clave abandonan a empresa ou cambian de función. As directrices vivas axudarán a garantir a integridade dos datos.
Se precisas escribir texto longo, Markdown é unha excelente alternativa ao HTML. Ás veces, a sintaxe de Markdown non é suficiente. Neste caso podemos usar HTML no seu interior. Por exemplo, elementos personalizados. Polo tanto, se está a construír un sistema de deseño con compoñentes web nativos, pódense incluír facilmente na documentación de texto. Se estás a usar React (ou calquera outro marco JSX como Preact ou Vue), podes facer o mesmo usando MDX.
Este artigo é unha ampla visión xeral das ferramentas para escribir documentación e crear directrices. Non todas as ferramentas enumeradas aquí usan MDX, pero cada vez se inclúe máis nas ferramentas de documentación.
Que é MDX?
arquivo .mdx ten a mesma sintaxe que Markdown, pero permíteche importar compoñentes JSX interactivos e incorporalos ao teu contido. O soporte para os compoñentes de Vue está en alfa. Para comezar a traballar con MDX, basta con instalar "Crear aplicación React". Hai complementos para Next.js e Gatsby. A próxima versión de Docusaurus (versión 2) tamén terá soporte nativo.
Redacción de documentación con Docusaurus
Docusaurus escribiu en Facebook. Utilízano en todos os proxectos de código aberto excepto React. Fóra da empresa é usado por Redux, Prettier, Gulp e Babel.
Proxectos que usan Docusaurus.
Docusaurus pódese usar para escribir calquera documentación, non só para describir o frontend. Ten React debaixo do capó, pero non tes que estar familiarizado con el para usalo. Leva os teus ficheiros Markdown, un chisco de maxia e está lista unha documentación ben estruturada, formatada e lexible cun deseño fermoso.
No sitio web de Redux podes ver o modelo estándar de Docusaurus
Os sitios web creados con Docusaurus tamén poden incluír un blog baseado en Markdown. Prism.js está conectado inmediatamente para resaltar a sintaxe. A pesar de que Docusaurus apareceu recentemente, foi recoñecida como a mellor ferramenta de 2018 en StackShare.
Outras opcións de creación de contidos
Docusaurus está deseñado especificamente para crear documentación. Por suposto, hai un millón e unha de formas de crear un sitio web: podes implementar a túa propia solución en calquera idioma, CMS ou usar un xerador de sitios estáticos.
Por exemplo, a documentación para React, o sistema de deseño de IBM, Apollo e Ghost CMS usan Gatsby, un xerador de sitios estáticos que se usa a miúdo para blogs. Se traballas con Vue, VuePress é unha boa opción para ti. Outra opción é usar un xerador escrito en Python - MkDocs. É de código aberto e configúrase mediante un único ficheiro YAML. GitBook tamén é unha boa opción, pero só é gratuíto para equipos públicos e non comerciais. Tamén pode simplemente cargar ficheiros mardown usando Git e traballar con eles en Github.
Compoñentes de documentación: Docz, Storybook e Styleguidist
Directrices, deseño do sistema, bibliotecas de compoñentes: como se chame, volveuse moi popular ultimamente. A chegada de marcos de compoñentes como React e as ferramentas mencionadas aquí transformáronos de proxectos de vanidade en ferramentas útiles.
Storybook, Docz e Styleguidist fan o mesmo: mostrar elementos interactivos e documentar a súa API. Un proxecto pode ter decenas ou mesmo centos de compoñentes, todos con diferentes estados e estilos. Se queres que os compoñentes sexan reutilizados, a xente debe saber que existen. Para iso, basta con catalogar os compoñentes. As directrices ofrecen unha visión xeral fácil de atopar de todos os seus compoñentes. Isto axuda a manter a consistencia visual e evitar traballos repetitivos.
Estas ferramentas ofrecen un xeito cómodo de ver diferentes estados. Pode ser difícil reproducir cada estado dun compoñente no contexto dunha aplicación real. En lugar de facer clic na aplicación real, paga a pena desenvolver un compoñente separado. Pódense simular estados de difícil acceso (como os estados de carga).
Xunto cunha demostración visual de varios estados e unha lista de propiedades, moitas veces é necesario escribir unha descrición xeral do contido: fundamentos de deseño, casos de uso ou descricións dos resultados das probas de usuarios. Markdown é moi sinxelo de aprender; idealmente, as directrices deberían ser un recurso compartido para deseñadores e desenvolvedores. Docz, Styleguidist e Storybook ofrecen un xeito de mesturar facilmente Markdown con compoñentes.
Docz
Actualmente Docz só funciona con React, pero está en marcha un traballo activo para admitir Preact, Vue e os compoñentes web. Docz é a máis recente das tres ferramentas, pero conseguiu recoller máis de 14 estrelas en Github. Docz introduce dous compoñentes − <Playground> и < Props >. Son importados e utilizados en ficheiros .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Podes envolver os teus propios compoñentes de React <Playground>para crear un análogo do CodePen ou CodeSandbox incorporado, é dicir, ve o seu compoñente e pode editalo.
<Playground>
<Button>click</Button>
</Playground><Props> mostrará todas as propiedades dispoñibles para un determinado compoñente React, os valores predeterminados e se a propiedade é necesaria.
<Props of={Button} />Persoalmente, creo que este enfoque baseado en MDX é o máis fácil de entender e o máis fácil de traballar.
Se es fan do xerador de sitios estáticos de Gatsby, Docz ofrece unha gran integración.
Guía de estilo
Do mesmo xeito que Docz, os exemplos escríbense usando a sintaxe de Markdown. Styleguidist usa bloques de código Markdown (comiñas triples) nos ficheiros normais .md ficheiros, non MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Os bloques de código en Markdown normalmente só mostran código. Cando se usa Styleguidist, calquera bloque de código cunha etiqueta de idioma js, jsx ou javascript renderase como un compoñente React. Do mesmo xeito que Docz, o código é editable: podes cambiar as propiedades e ver o resultado ao instante.
Styleguidist creará automaticamente unha táboa de propiedades a partir das declaracións PropTypes, Flow ou Typescript.
Styleguidist actualmente admite React e Vue.
Libro de contos
Storybook sitúase como un "entorno de desenvolvemento de compoñentes de IU". En lugar de escribir compoñentes de exemplo dentro de ficheiros Markdown ou MDX, escribe historias dentro de ficheiros Javascript. Historia documentar o estado específico dun compoñente. Por exemplo, un compoñente pode ter historiais para un estado cargado e un estado desactivado (válido).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook é moito máis complexo que Styleguidist e Docz. Pero ao mesmo tempo, esta é a opción máis popular; o proxecto ten máis de 36 estrelas en Github. É un proxecto de código aberto con 000 colaboradores e persoal a tempo completo. É usado por Airbnb, Algolia, Atlassian, Lyft e Salesforce. Storybook admite máis marcos que os competidores: React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte e HTML normal.
Nunha versión futura haberá funcións de Docz e introduciranse MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>As novas funcións de Storybook lanzaranse gradualmente nos próximos meses e parece que será un gran paso adiante.
Resultados de
Os beneficios dunha biblioteca de patróns son exaltados en millóns de artigos en Medium. Cando se fan ben, facilitan a creación de produtos relacionados e o mantemento da identidade. Por suposto, ningunha destas ferramentas creará máxicamente un sistema de deseño. Isto require un deseño coidadoso e CSS. Pero cando chega o momento de facer un sistema de deseño accesible para toda a empresa, Docz, Storybook e Styleguidist son excelentes opcións.
Do tradutor. Esta é a miña primeira experiencia en Habré. Se atopas algunha imprecisión ou tes suxestións para mellorar o artigo, escríbeme nunha mensaxe persoal.
Fonte: www.habr.com