Marcus Andrey Estudo
Read in English Biblioteca

Design systems · Laboratórios · 5 min de leitura

Escreva a página de documentação de um componente

Um laboratório guiado: escreva a página de documentação de um componente, na ordem em que as pessoas fazem as perguntas. Junte as perguntas reais, preencha um modelo, escreva regras de uso com motivo e teste a página com um designer e um dev que nunca usaram o componente. Cerca de duas horas.

Uma página de documentação é lida por alguém com pressa, no meio de uma tela, com uma pergunta só. Se a resposta está na primeira tela, a pessoa usa o componente do jeito certo. Se está no sexto parágrafo, ela chuta, pergunta no chat ou faz o próprio. Você vai escrever uma página para um componente, começando pelas perguntas que as pessoas fazem de verdade, e testá-la com duas pessoas que nunca o usaram.

O que você vai fazer:

  • Juntar as perguntas reais que as pessoas fazem sobre um componente
  • Preencher um modelo de página de documentação, de cima para baixo
  • Escrever regras de uso com um motivo e um exemplo
  • Testar a página com um designer e um dev

Você vai precisar de: um componente do seu sistema (ou o Notice do Harbour, como no exemplo), um lugar para escrever (a sua ferramenta de documentação, um arquivo Markdown ou uma página no Figma), um histórico de chat ou de tickets para pesquisar, cerca de duas horas.


1. Junte as perguntas

Antes de escrever, procure o nome do componente no chat do time, nos tickets e nas revisões de design. Anote cada pergunta que encontrar, palavra por palavra. Para um aviso, elas soam assim:

  • "Posso usar isso para um erro de formulário?"
  • "Pode ter um botão?"
  • "Qual eu uso para 'travessia cancelada'?"
  • "O leitor de tela lê em voz alta?"

Ordene pela frequência. As três primeiras vão para a primeira tela da página.


2. Use um modelo, na ordem em que as pessoas perguntam

  • Notice
  • Uso
  • Propriedades
  • Acessibilidade
  • Conteúdo
  • Changelog

NoticeEstável · desde a 3.2.0Figma · React · Storybook

Avisa as pessoas sobre algo que afeta a página ou a tarefa inteira, sem interromper.

A travessia das 08:40 está atrasada 30 minutosO check-in fecha às 09:00. O seu lugar está garantido.

Quando usar, e quando não

UsePara notícias sobre uma reserva ou uma travessia que as pessoas precisam ver antes de agir.
Não usePara erros num campo (use o texto de erro do campo) ou para confirmações que pedem resposta (use Dialog).

Propriedades

tone: info, success, warning, danger · title: texto · dismissible: booleana · action: slot, no máximo um link ou botão.

Acessibilidade

  • Renderizado com role="status"; avisos danger que aparecem depois de uma ação usam role="alert".
  • O tom está nas palavras além da cor: o título diz o que aconteceu.
  • Texto 15,58:1 sobre sand.50; a borda coral é decoração, não a mensagem.

Conteúdo

Título: o que aconteceu, em menos de 60 caracteres. Corpo: o que isso significa para a pessoa e o que fazer. Nada de "Ops".

Changelog

3.6.0 · slot action adicionado · 3.2.0 · primeira versão, substitui o Banner.

Uma página de documentação preenchida para um componente do Harbour, de cima para baixo na ordem em que as pessoas perguntam: o que é, posso usar aqui, como configuro, é acessível, o que escrevo, o que mudou. Tudo o que um designer precisa na primeira tela, o detalhe embaixo.Exemplo: Marcus Andrey, CC BY 4.0. Ordem das seções inspirada nas páginas de componente do GOV.UK Design System.

As páginas de componente do GOV.UK Design System abrem com quando usar o componente, depois como ele funciona, depois a pesquisa por trás dele (GOV.UK Design System, Button). A ordem importa mais do que os títulos exatos. Copie este modelo:

# Nome do componente   [status · desde a versão]   [Figma] [Código] [Storybook]

Uma frase: o que ele faz por quem usa o produto.

[Exemplo ao vivo, configuração padrão]

## Quando usar
## Quando não usar  (e o que usar no lugar)
## Como funciona
   Variantes e propriedades, cada uma com um exemplo
## Acessibilidade
   Papel (role), teclado, o que é anunciado, contraste
## Conteúdo
   Como escrever o texto dentro dele
## Pesquisa e decisões
## Changelog

Deixe na primeira tela só o nome, o status, a frase, o exemplo e o "quando usar / quando não usar". É disso que a maioria das visitas precisa.


3. Escreva regras de uso que as pessoas seguem

Cada regra precisa de três coisas:

  • A regra, como algo que dá para conferir: "Um aviso por página", e não "use com moderação".
  • O motivo, em uma linha: "Dois avisos competem, e as pessoas não leem nenhum."
  • Um exemplo: um faça e um não faça, como imagens ou exemplos ao vivo.

No "quando não usar", sempre diga a alternativa. "Não use para erros num campo: use a mensagem de erro do campo" ajuda. "Não use para erros" deixa a pessoa sem saída.


4. Escreva a seção de acessibilidade para os dois leitores

Designers precisam saber o que têm que fornecer; devs precisam saber o que o componente faz. Para um aviso:

  • Papel: role="status" para informação que chega sem interromper, role="alert" só para mensagens importantes e urgentes. O padrão de alerta do APG descreve alertas como informação importante e potencialmente urgente, e avisa que interrupções frequentes atrapalham a usabilidade para pessoas com deficiências visuais e cognitivas (WAI-ARIA APG, Alert).
  • Não só pela cor: o tom precisa ficar claro também pelas palavras (W3C, Understanding 1.4.1).
  • Contraste: a razão medida do texto sobre o fundo, por escrito. O ink.900 sobre sand.50 do Harbour dá 15,58:1.

5. Escreva as propriedades e o changelog

Liste cada propriedade com os valores e o padrão, com os mesmos nomes do Figma e do código (veja Desenhe um componente com variantes no Figma). Se você tem Storybook, aponte para a story ou incorpore os controles dela em vez de copiar a tabela à mão, para que ela não fique desatualizada (veja Storybook e documentação viva).

O changelog no fim da página responde "isso mudou desde a última vez que usei?". Uma versão, uma data, uma linha cada.


6. Teste a página

Entregue a página a um designer e um dev que não usaram o componente. Dê uma tarefa a cada um:

  • Designer: "Coloque um aviso nesta tela dizendo que a travessia das 08:40 está atrasada."
  • Dev: "Implemente, e me diga o que um leitor de tela vai falar."

Observe, não ajude. Cada vez que a pessoa rolar procurando algo, ou te perguntar, anote a pergunta. Essa pergunta é uma linha que falta, ou uma linha no lugar errado.


7. Confira seu trabalho

Perguntas para refletir: Qual pergunta apareceu mais, e ela já tinha resposta em algum lugar onde ninguém olhou? O que você tiraria da página se ela só pudesse ter metade do tamanho?

Relacionadas

Documentação de componentes que as pessoas usam · Storybook e documentação viva · Conteúdo e voz no sistema · Documentar o movimento num design system · Componentes acessíveis · Modelo de página de componente

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar