Você pode ter um projeto de código aberto melhor, mas se ele não tiver uma boa documentação, é provável que nunca decole. No escritório, uma boa documentação permitirá que você não responda às mesmas perguntas. A documentação também garante que as pessoas possam entender o projeto se os principais funcionários deixarem a empresa ou as funções mudarem. As diretrizes ativas ajudam a garantir a integridade dos dados.
Se você precisar escrever um texto longo, o Markdown é uma ótima alternativa ao HTML. Às vezes, a sintaxe do Markdown não é suficiente. Nesse caso, podemos usar o HTML dentro dele. Por exemplo, elementos personalizados. Portanto, se você estiver construindo um sistema de design com componentes da Web nativos, eles serão fáceis de incluir na documentação de texto. Se você usar o React (ou qualquer outra estrutura JSX como Preact ou Vue), poderá fazer o mesmo com o MDX.
Este artigo é uma visão geral das ferramentas de redação e orientação de documentação. Nem todas as ferramentas listadas aqui usam MDX, mas estão sendo cada vez mais incluídas nas ferramentas de documentação.
O que é MDX?
O arquivo .mdx tem a mesma sintaxe que o Markdown, mas permite importar componentes interativos JSX e incorporá-los ao seu conteúdo. O suporte para componentes do Vue está em alfa. Para começar a trabalhar com o MDX, basta instalar o "Create React App". Existem plugins para o Next.js e o Gatsby. A próxima versão do Docusaurus (versão 2) também terá suporte interno.
Escrevendo documentação com o Docusaurus
Docusaurus escreveu no Facebook. Eles o usam em todos os projetos de código aberto, exceto no React. Fora da empresa, Redux, Prettier, Gulp e Babel usam.
Projetos que usam o Docusaurus.
O Docusaurus pode ser usado para escrever qualquer documentação, não apenas para descrever o frontend. Ele reage sob o capô, mas, para usá-lo, não é necessário estar familiarizado com ele. Leva seus arquivos Markdown, uma pitada de magia e documentação bem estruturada, formatada e legível com um belo design pronto.
No site do Redux, você pode ver o modelo padrão do Docusaurus
Os sites criados com o Docusaurus também podem incluir um blog baseado no Markdown. O Prism.js é imediatamente conectado ao realce da sintaxe. Apesar do Docusaurus ter aparecido relativamente recentemente, foi reconhecido como a melhor ferramenta de 2018 no StackShare.
Outras opções de criação de conteúdo
O Docusaurus foi projetado especificamente para criar documentação. Obviamente, há um milhão e uma maneira de criar um site - você pode implantar sua própria solução em qualquer idioma, CMS ou usar o gerador de site estático.
Por exemplo, a documentação do React, o sistema de design da IBM, Apollo e Ghost CMS, usa o Gatsby - um gerador de site estático que é frequentemente usado em blogs. Se você trabalha com o Vue, o VuePress é uma boa opção para você. Outra opção é usar um gerador escrito em Python - MkDocs. É aberto e configurável com um único arquivo YAML. O GitBook também é uma boa opção, mas é gratuito apenas para equipes abertas e sem fins lucrativos. E você pode simplesmente fazer upload de arquivos mardown usando o gith e trabalhar com eles no Github.
Documentação do componente: Docz, Storybook e Styleguidist
Diretrizes, design de sistema, bibliotecas de componentes - como você os chama, mas tornou-se muito popular ultimamente. O advento das estruturas de componentes, como o React e as ferramentas mencionadas aqui, tornou possível transformá-las de projetos arrogantes em ferramentas úteis.
Storybook, Docz e Styleguidist - faça o mesmo: exiba elementos interativos e documente sua API. Um projeto pode ter dezenas ou mesmo centenas de componentes - todos com diferentes estados e estilos. Se você deseja que os componentes sejam reutilizados, as pessoas precisam saber que elas existem. Para fazer isso, basta catalogar os componentes. As diretrizes fornecem uma visão geral pesquisável de todos os seus componentes. Isso ajuda a manter a consistência visual e a evitar trabalhos repetitivos.
Essas ferramentas fornecem uma maneira conveniente de visualizar vários estados. Pode ser difícil reproduzir cada estado do componente no contexto de um aplicativo real. Em vez de clicar em um aplicativo real, você deve desenvolver um componente separado. Você pode simular estados de difícil acesso (por exemplo, status de inicialização).
Juntamente com uma demonstração visual de vários estados e uma lista de propriedades, geralmente é necessário escrever uma descrição geral do conteúdo - justificativas de design, estudos de caso ou uma descrição dos resultados dos testes do usuário. O Markdown é muito fácil de aprender - idealmente, as diretrizes devem ser um recurso compartilhado para designers e desenvolvedores. Docz, Styleguidist e Storybook oferecem uma maneira de misturar facilmente o Markdown com os componentes.
Docz
Agora, o Docz funciona apenas com o React, mas existe um trabalho ativo no suporte a Preact, Vue e componentes da web. Docz é o mais novo dos três instrumentos, mas no Github ele conseguiu coletar mais de 14.000 estrelas. Docz representa dois componentes - <Playground> e < Props > . Eles são importados e usados em arquivos .mdx .
import { Playground, Props } from "docz"; import Button from "../src/Button"; ## You can _write_ **markdown** ### You can import and use components <Button>click</Button>
Você pode agrupar seus próprios componentes do React com <Playground> para criar um análogo do CodePen ou CodeSandbox interno - ou seja, você vê seu componente e pode editá-lo.
<Playground> <Button>click</Button> </Playground>
<Props> mostrará todas as propriedades disponíveis para esse componente React, os valores padrão e se uma propriedade é necessária.
<Props of={Button} />
Pessoalmente, acho que essa abordagem baseada em MDX é a mais fácil de entender e mais fácil de trabalhar.
Se você é um fã do gerador de sites estáticos Gatsby, o Docz oferece ótima integração.
Styleguidist
Como o Docz, exemplos são escritos usando a sintaxe do Markdown. O Styleguidist usa blocos de código Markdown (aspas triplas) em arquivos .md regulares, não no MDX.
```js <Button onClick={() => console.log('clicked')>Push Me</Button>
Blocos de código no Markdown geralmente apenas mostram o código. Ao usar o Styleguidist, qualquer bloco de código com uma tag de idioma js , jsx ou javascript será exibido como um componente React. Como no Docz, o código é editável - você pode alterar as propriedades e ver instantaneamente o resultado.
O Styleguidist criará automaticamente uma tabela de propriedades a partir das declarações PropTypes, Flow ou Typescript.
O Styleguidist agora suporta React e Vue.
Livro de histórias
O Storybook se posiciona como um "ambiente de desenvolvimento para componentes da interface do usuário". Em vez de escrever exemplos de componentes em arquivos Markdown ou MDX, você escreve histórias em arquivos Javascript. O histórico é documentado pelo estado específico do componente. Por exemplo, um componente pode ter históricos para o estado de inicialização e o estado desabilitado.
storiesOf('Button', module) .add('disabled', () => ( <Button disabled>lorem ipsum</Button> ))
O livro de histórias é muito mais complicado que o Styleguidist e Docz. Mas, ao mesmo tempo, essa é a opção mais popular, no Github o projeto tem mais de 36.000 estrelas. Este é um projeto de código aberto, envolve 657 participantes e é acompanhado por funcionários em período integral. É usado pelo Airbnb, Algolia, Atlassian, Lyft e Salesforce. O Storybook suporta mais estruturas do que seus concorrentes - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte e HTML comum.
Em uma versão futura, haverá chips da Docz e o MDX será introduzido.
# Button Some _notes_ about your button written with **markdown syntax**. <Story name="disabled"> <Button disabled>lorem ipsum</Button> </Story>
Os novos recursos do livro de histórias aparecerão gradualmente nos próximos meses e, aparentemente, este será um grande passo à frente.
Sumário
Os benefícios da biblioteca de padrões são exaltados em milhões de artigos no Medium. Quando bem executados, facilitam a criação de produtos relacionados e a manutenção da identidade. Obviamente, nenhuma dessas ferramentas criará magicamente um sistema de design. Isso requer design cuidadoso e design CSS. Mas quando chega a hora de disponibilizar o sistema de design para toda a empresa, Docz, Storybook e Styleguidist são ótimas opções.
Do tradutor. Esta é a minha primeira experiência em Habré. Se você achar que alguns não são precisos, ou existem sugestões para melhorar o artigo - escreva em um artigo pessoal.