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 evitará que você responda às mesmas perguntas repetidamente. 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 ao vivo ajudam a garantir a integridade dos dados.
Se você precisa escrever um texto longo, o Markdown é uma ótima alternativa ao HTML. Às vezes, a sintaxe Markdown não é suficiente. Nesse caso, podemos usar HTML dentro dele. Por exemplo, elementos personalizados. Portanto, se você estiver construindo um sistema de design com componentes da Web nativos, é fácil incluí-los na documentação de texto. Se você estiver usando React (ou qualquer outro framework JSX como Preact ou Vue), você pode fazer o mesmo com MDX.
Este artigo é uma ampla visão geral das ferramentas para escrever documentação e criar uma diretriz. Nem todas as ferramentas listadas aqui usam MDX, mas ele está sendo cada vez mais incluído em ferramentas de documentação.
O que é MDX?
arquivo .mdx tem a mesma sintaxe do Markdown, mas permite importar componentes JSX interativos e incorporá-los ao seu conteúdo. O suporte para componentes Vue está em alfa. Para começar a trabalhar com MDX, basta instalar "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
Docusaurus escreveu no Facebook. Eles o usam em todos os projetos de código aberto, exceto React. Fora da empresa, Redux, Prettier, Gulp e Babel o utilizam.
Projetos que usam Docusaurus.
Docusaurus pode ser usado para escrever qualquer documentação, não apenas para descrever o frontend. Ele tem React sob o capô, mas você não precisa estar familiarizado com ele para usá-lo. Leva seus arquivos Markdown, uma pitada de mágica e está pronta uma documentação bem estruturada, formatada e legível com um belo design.
Você pode ver o modelo padrão do Docusaurus no site do Redux.
Sites criados com Docusaurus também podem incluir um blog baseado em Markdown. Para destaque de sintaxe, Prism.js é imediatamente incluído. Apesar de o Docusaurus ter surgido há relativamente pouco tempo, foi reconhecido como a melhor ferramenta de 2018 no StackShare.
Outras opções de criação de conteúdo
Docusaurus é projetado especificamente para criar documentação. Claro, existem milhões e uma maneiras de criar um site - você pode implantar sua própria solução em qualquer idioma, CMS ou usar um gerador de site estático.
Por exemplo, a documentação para React, o sistema de design IBM, Apollo e Ghost CMS usam Gatsby, um gerador de site estático frequentemente usado para blogs. Se você estiver trabalhando com o Vue, o VuePress é uma boa opção para você. Outra opção é usar um gerador escrito em Python - MkDocs. Ele é aberto e configurado com um único arquivo YAML. O GitBook também é uma boa opção, mas é gratuito apenas para equipes abertas e não comerciais. Você também pode simplesmente carregar arquivos mardown usando git e trabalhar com eles no Github.
Documentação do componente: Docz, Storybook e Styleguidist
Diretrizes, design de sistema, bibliotecas de componentes, como você quiser chamá-los, tornaram-se muito populares ultimamente. O surgimento de frameworks de componentes como o React e as ferramentas mencionadas aqui tornaram possível transformá-los de projetos vaidosos em ferramentas úteis.
Storybook, Docz e Styleguidist fazem a mesma coisa: exibem elementos interativos e documentam sua API. Um projeto pode ter dezenas ou até centenas de componentes, todos com diferentes estados e estilos. Se você deseja que os componentes sejam reutilizados, as pessoas precisam saber que eles existem. Para isso, basta catalogar os componentes. As diretrizes fornecem uma visão geral fácil de pesquisar de todos os seus componentes. Isso ajuda a manter a consistência visual e evitar o trabalho repetitivo.
Essas ferramentas fornecem uma maneira conveniente de visualizar vários estados. Pode ser difícil replicar cada estado de um componente no contexto de um aplicativo real. Em vez de clicar no aplicativo real, vale a pena desenvolver um componente separado. É possível modelar estados de difícil acesso (por exemplo, estado de carregamento).
Juntamente com uma demonstração visual de vários estados e uma lista de propriedades, muitas vezes é necessário escrever uma descrição geral do conteúdo - justificativas de design, casos de uso ou uma descrição dos resultados do teste do usuário. Markdown é muito fácil de aprender - idealmente, as diretrizes devem ser um recurso compartilhado por designers e desenvolvedores. Docz, Styleguidist e Storybook oferecem uma maneira de misturar Markdown facilmente com componentes.
Documento
Atualmente, Docz trabalha apenas com React, mas está trabalhando ativamente no suporte para Preact, Vue e componentes da web. Docz é a mais recente das três ferramentas, mas conseguiu coletar mais de 14 estrelas no Github. Docz apresenta dois componentes - <Playground> и < 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 React com <Playground>para criar um análogo do CodePen ou CodeSandbox integrado - ou seja, você vê seu componente e pode editá-lo.
<Playground>
<Button>click</Button>
</Playground><Props> mostrará todas as propriedades disponíveis para o componente React fornecido, valores padrão e se a propriedade é necessária.
<Props of={Button} />Pessoalmente, acho essa abordagem baseada em MDX a mais fácil de entender e trabalhar.
Se você é fã do gerador de sites estáticos do Gatsby, o Docz oferece ótimas integrações.
guia de estilo
Como no Docz, os exemplos são escritos usando a sintaxe Markdown. Styleguidist usa blocos de código Markdown (aspas triplas) em arquivos regulares .md arquivos, não em MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Os blocos de código no Markdown geralmente mostram apenas o código. Ao usar o Styleguidist, qualquer bloco de código com uma tag de idioma js, jsx ou javascript renderizará como um componente React. Como o Docz, o código é editável - você pode alterar as propriedades e ver instantaneamente o resultado.
O Styleguidist criará automaticamente uma folha de propriedades a partir das declarações PropTypes, Flow ou Typescript.
Styleguidist agora suporta React e Vue.
Livro de histórias
O Storybook se autodenomina um "ambiente de desenvolvimento de componentes de interface do usuário". Em vez de escrever exemplos de componentes dentro de arquivos Markdown ou MDX, você escreve histórias dentro de arquivos Javascript. história documentar o estado específico de um componente. Por exemplo, um componente pode ter históricos para um estado de carregamento e um estado desabilitado (inválido).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook é muito mais complexo do que Styleguidist e Docz. Mas, ao mesmo tempo, esta é a opção mais popular, no Github o projeto tem mais de 36 estrelas. Este é um projeto de código aberto com 000 colaboradores e acompanhamento de equipe. É usado por Airbnb, Algolia, Atlassian, Lyft e Salesforce. O Storybook suporta mais estruturas do que a concorrência - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte e HTML simples.
Em uma versão futura, haverá chips da Docz e o MDX está sendo introduzido.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Os novos recursos do Storybook serão lançados gradualmente nos próximos meses e parece que será um grande passo à frente.
Resultados de
Os benefícios da biblioteca de padrões são elogiados em milhões de artigos no Medium. Quando bem feitos, facilitam a criação de produtos relacionados e mantêm uma 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.
De um tradutor. Esta é a minha primeira experiência no Habr. Se você encontrar alguma imprecisão ou tiver sugestões para melhorar o artigo - escreva em um pessoal.
Fonte: habr.com