Você pode ter o melhor projeto de código aberto, mas se não houver uma boa documentação, há uma boa chance de que ele nunca decole. No escritório, uma boa documentação evita que você tenha que responder às mesmas perguntas repetidamente. A documentação também garante que as pessoas possam entender o projeto se funcionários-chave saírem da empresa ou se os papéis mudarem. Diretrizes ao vivo ajudam a garantir a integridade dos dados.
Se você precisa escrever um texto longo, Markdown é uma ótima alternativa ao HTML. Às vezes, a sintaxe do Markdown não é suficiente. Neste caso, podemos usar HTML dentro dele. Por exemplo, elementos personalizados. Portanto, se você estiver construindo um sistema de design com componentes web nativos, é fácil incorporá-los na documentação textual. Se você estiver usando React (ou qualquer outro framework JSX, como Preact ou Vue), pode fazer isso da mesma forma usando MDX.
Este artigo é uma visão geral abrangente de ferramentas para escrever documentação e criar diretrizes. Nem todas as ferramentas listadas aqui utilizam MDX, mas ele está sendo cada vez mais incorporado em ferramentas de documentação.
O que é MDX?
Arquivo .mdx possui a mesma sintaxe que o Markdown, mas permite importar componentes interativos JSX e incorporá-los ao seu conteúdo. O suporte a componentes Vue está em fase alfa. Para começar a trabalhar com MDX, basta instalar o 'Create React App'. Existem plugins para Next.js e Gatsby. A próxima versão do Docusaurus (versão 2) também terá suporte integrado.
Escrevendo documentação com Docusaurus
O Docusaurus foi desenvolvido pelo Facebook. Ele é utilizado em todos os projetos de código aberto, exceto o React. Fora da empresa, ele é utilizado pelo Redux, Prettier, Gulp e Babel.
Projetos que utilizam Docusaurus.
O Docusaurus pode ser usado para escrever (lembrando das pessoas em posições elevadas), isso é ruim documentação, não apenas para descrever o frontend. Ele é baseado em React, mas não é necessário estar familiarizado com ele para utilizá-lo. Ele pega seus arquivos Markdown, um toque de mágica e uma documentação bem estruturada, formatada e legível, com um design bonito, está pronta.
No site do Redux, você pode ver o modelo padrão do Docusaurus.
Sites criados com Docusaurus também podem incluir um blog baseado em Markdown. A sintaxe é destacada automaticamente com Prism.js. Embora o Docusaurus tenha sido lançado relativamente há pouco tempo, já foi reconhecido como a melhor ferramenta de 2018 no StackShare.
Outras opções para criação de conteúdo
Docusaurus foi especificamente projetado para criar documentação. Claro, existem milhões de maneiras de fazer um site — você pode implementar sua própria solução em qualquer linguagem, CMS ou usar um gerador de sites estáticos.
Por exemplo, a documentação para React, a IBM Design System, Apollo e Ghost CMS usam Gatsby — um gerador de sites estáticos que é frequentemente utilizado para blogs. Se você está trabalhando com Vue, VuePress pode ser uma boa opção para você. Outra alternativa é usar um gerador escrito em Python — MkDocs. Ele é open-source e configurado através de um único arquivo YAML. GitBook também é uma boa opção, mas é gratuito apenas para equipes abertas e não comerciais. Além disso, você pode simplesmente enviar arquivos Markdown usando git e trabalhar com eles no Github.
Documentação de componentes: Docz, Storybook e Styleguidist
Diretrizes, sistemas de design, bibliotecas de componentes — como você os chama, se tornaram muito populares recentemente. O surgimento de frameworks de componentes, como React, e as ferramentas mencionadas aqui — permitiu que se transformassem de projetos fúteis em ferramentas úteis.
Storybook, Docz e Styleguidist fazem a mesma coisa: exibem elementos interativos e documentam suas APIs. Um projeto pode ter dezenas ou até centenas de componentes — todos com diferentes estados e estilos. Se você quer que os componentes sejam reutilizados, as pessoas precisam saber que eles existem. Para isso, é suficiente catalogar os componentes. As diretrizes fornecem uma visão geral que é fácil de pesquisar de todos os seus componentes. Isso ajuda a manter a consistência visual e evitar trabalho duplicado.
Essas ferramentas oferecem uma maneira conveniente de visualizar diferentes estados. Pode ser difícil reproduzir cada estado de um componente no contexto de um aplicativo real. Em vez de clicar em um aplicativo real, é melhor desenvolver um componente separado. Você pode simular estados de difícil acesso (por exemplo, estado de carregamento).
Além da demonstração visual de vários estados e da lista de propriedades, muitas vezes é necessário escrever uma descrição geral do conteúdo — justificativas de design, casos de uso ou descrição dos resultados de testes com usuários. O Markdown é muito fácil de aprender — idealmente, as diretrizes devem ser um recurso colaborativo para designers e desenvolvedores. Docz, Styleguidist e Storybook oferecem uma maneira fácil de misturar Markdown com componentes.
Docz
Atualmente, o Docz funciona apenas com React, mas há um trabalho ativo para suportar Preact, Vue e componentes da web. O Docz é a ferramenta mais nova das três, mas conseguiu reunir mais de 14.000 estrelas no Github. O Docz apresenta dois componentes — <Playground> e < Props >. Eles são importados e usados em arquivos .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Você pode _escrever_ **markdown**
### Você pode importar e usar componentes
Você pode envolver seus próprios componentes React com <Playground>, para criar algo semelhante ao CodePen ou CodeSandbox integrados — ou seja, você vê seu componente e pode editá-lo.
<Props> mostrará todas as propriedades disponíveis para este componente React, valores padrão e se a propriedade é obrigatória.
<Props of={Button} />Pessoalmente, considero essa abordagem baseada em MDX a mais fácil de entender e a mais simples de trabalhar.
Se você é fã do gerador de sites estáticos Gatsby, o Docz oferece uma excelente integração.
Styleguidist
Assim como no Docz, os exemplos são escritos usando a sintaxe Markdown. O Styleguidist utiliza blocos de código Markdown (três aspas) em arquivos normais .md em vez de MDX.
```js
Os blocos de código no Markdown normalmente mostram apenas o código. Ao usar o Styleguidist, qualquer bloco de código com a tag de linguagem js, jsx ou javascript será exibido como um componente React. Assim como no Docz, o código é editável — você pode alterar as propriedades e ver o resultado instantaneamente.
O Styleguidist gerará automaticamente uma tabela de propriedades a partir de declarações PropTypes, Flow ou Typescript.
Atualmente, o Styleguidist suporta React e Vue.
Storybook
O Storybook se posiciona como "um ambiente de desenvolvimento de componentes de UI". Em vez de escrever exemplos de componentes dentro de arquivos Markdown ou MDX, você escreve histórias dentro de arquivos Javascript. Histórico documentam um estado específico do componente. Por exemplo, um componente pode ter histórias para um estado de carregamento e um estado desativado (desativado).
storiesOf('Button', module)
.add('desativado', () => (
))O Storybook é muito mais complexo que o Styleguidist e o Docz. No entanto, é a opção mais popular, com mais de 36.000 estrelas no GitHub. É um projeto de código aberto, com 657 colaboradores e apoiado por funcionários dedicados. É utilizado por Airbnb, Algolia, Atlassian, Lyft e Salesforce. O Storybook suporta mais frameworks do que seus concorrentes — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte e HTML comum.
Na próxima versão, recursos do Docz serão incorporados e o MDX será implementado.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Novas funcionalidades do Storybook serão lançadas gradualmente nos próximos meses e, aparentemente, será um grande avanço.
Resultados
As vantagens da biblioteca de padrões são exaltadas em milhões de artigos no Medium. Quando tudo é bem feito, elas facilitam a criação de produtos relacionados e a manutenção da identidade. Claro, nenhuma dessas ferramentas ajudará magicamente a criar um sistema de design. Isso requer um cuidadoso planejamento de design e CSS. Mas quando chegar a hora de disponibilizar o sistema de design para toda a empresa, o Docz, Storybook e Styleguidist são ótimas opções.
Do tradutor. Esta é a minha primeira experiência no Habr. Se você encontrou alguma imprecisão ou tem sugestões para melhorar o artigo, envie uma mensagem privada.
Fonte: habr.com
