No outono de 2016, eu e meu colega fomos instruídos a melhorar a documentação e o conteúdo da minha antiga empresa. Passamos um ano em todos os tipos de documentação: referência de API, guias, tutoriais, postagens de blog. Antes disso, escrevi docas por 5 anos, mas não aprendi isso oficialmente. Mas não posso ser chamado de inexperiente: além de documentar a API para projetos e startups, também ensinei Python Flask em seminários enquanto estudava nos últimos cursos da universidade. Mas agora é uma oportunidade de focar apenas no meu negócio favorito: ajudar especialistas de todos os níveis através da documentação técnica.

Este ano, aprendi muito com a comunidade Write The Docs, com outros provedores de API e com o método de tentativa e erro. No ano passado, compartilhei minha experiência no relatório “O que eu gostaria de saber sobre como escrever documentação” na Conferência de Estratégia e Prática da API de Portland. Este artigo é uma visão geral do conhecimento adquirido.

Como as pessoas realmente leem a documentação?

“Uma nação estremece com um grande fragmento de um único texto”, foto de The Onion

Você conhece esse sentimento como na foto? Isso acontece Talvez não fisicamente, mas provavelmente as pessoas estremecem mentalmente. Eu estava constantemente atormentado com o pensamento de que as pessoas não liam meus textos, a menos que eu os apresentasse de uma maneira facilmente digerível. Puxa, isso pode acontecer mesmo com este artigo.

Em um estudo de pesquisa do Neilson Norman Group em 2006, 232 usuários visualizaram milhares de páginas da web. Acontece que os usuários geralmente olham para as páginas usando o padrão F:

1. “Primeiro eles lêem na direção horizontal , geralmente na parte superior da área de conteúdo. Este é o elemento principal da figura F.
2. “Então eles se movem um pouco para baixo na página - e fazem um segundo movimento horizontal , que geralmente cobre uma área mais curta que a anterior. Este elemento adicional forma o elemento do meio da figura F ".
3. “Finalmente, os usuários digitalizam o lado esquerdo do conteúdo verticalmente . Às vezes, essa é uma varredura lenta e sistemática, exibida como uma faixa sólida em um mapa de calor. Às vezes, o movimento é mais rápido, formando pontos no mapa de calor. Este é o último elemento vertical na figura F. "

Mapas de calor Nielsen Norman Group

O estudo encontrou alguns padrões alternativos de digitalização, como um padrão de bolo folhado, mapa manchado, modelo de layout, padrão de desvio e padrão de propósito. Eu recomendo fortemente que você leia o relatório .

É importante observar que o modelo F está no caminho dos usuários , mas o bom posicionamento do conteúdo ajuda a impedir a digitalização.

Quais são as implicações específicas para a documentação?

• Os dois primeiros parágrafos devem indicar as informações mais importantes.
• As primeiras 3-5 palavras são críticas
• Cabeçalhos, parágrafos e listas com marcadores com palavras informativas
• Alterações de fonte (tamanho, links, negrito etc.) podem ser necessárias para manter a atenção do leitor

Então, como estruturar o conteúdo da página?

• Impedir a digitalização: verifique se as informações de que o leitor precisa estão destacadas
• Um pensamento em um parágrafo. Se houver vários, quebre o parágrafo
• Os usuários pulam tudo que parece banners, portanto, tenha cuidado com as ilustrações.
• Não expanda muito a coluna de texto: de maneira ideal 65 a 90 caracteres

Aprendi algumas dessas dicas na palestra de Kevin Burke , "Como escrever documentação para usuários que não lêem". Kevin deu suporte à documentação do Twilio de 2011 a 2014.

Além disso, os parágrafos têm suas próprias especificidades. Como o texto de The Onion , quando você lê muitos parágrafos, pode pular a essência. Então, por que usá-los com tanta frequência? Vamos fazer um experimento na documentação do Keen IO:

Leia rapidamente:

Os conjuntos de eventos podem ter quase qualquer nome, mas existem várias regras: o nome não deve ter mais que 64 caracteres. Ele deve conter apenas caracteres ASCII. Não pode ser nulo.

Agora leia rapidamente isso:

Os conjuntos de eventos podem ter quase qualquer nome, mas existem algumas regras:

• O título deve ter no máximo 64 caracteres
• Ele deve conter apenas caracteres ASCII
• Não pode ser nulo

Nos dois exemplos, exatamente o mesmo texto. Este não é o binômio de Newton: o segundo ajuda a absorver informações melhor e mais rapidamente. Se o parágrafo contiver uma lista de qualquer tipo, transforme-o em uma lista com marcadores.

Mais tarde discutiremos com mais detalhes o layout da documentação e a navegação.

Exemplos de código

O que é a documentação da API sem código, certo? Existem exemplos de código em muitos de nossos documentos, e os usuários realmente os lêem. Mas o problema é que eles nem sempre prestam atenção ao texto ao redor.

O contexto no código de amostra é crítico para o sucesso do desenvolvedor. Os desenvolvedores adoram copiar e colar rapidamente. Aqui está um exemplo com a API do Keen IO:

var client = new Keen({ projectId: "your_project_id", writeKey: "your_write_key" }); var ticketPurchase = { price: 50.00, user: { id: "020939382", age: 28 }, artist: { id: "19039", name: "Tycho" } } client.addEvent("ticket_purchases", ticketPurchase); 

O desenvolvedor copia e cola rapidamente esse código. E ...



Primeiro, como eles executam o arquivo? Provavelmente como o node file_name.js , mas isso não está no código. Pode-se indicar nos comentários no topo.

Bem, eles começaram e ... ReferenceError: Keen is not defined . :-( O cliente Keen não foi iniciado, na parte superior não há instruções de importação ou exigência, e só funciona após a instalação da biblioteca npm.

O usuário o corrigiu e o executou novamente ... Adivinha ?! Outro erro! your_project_id e your_write_key ausentes.

Tudo isso poderia ser mais óbvio.

Aqui está um exemplo da documentação do Twilio que fornece um bom contexto para o usuário final:


Captura de tela da documentação da biblioteca Twilio Node Helper

Isso esclarece imediatamente como instalar a biblioteca, incorporá-la ao seu código e o que precisa ser substituído no código de amostra antes de executá-lo.

Erros de copiar e colar

Como temos muitos códigos de amostra na documentação, copiar e colar com êxito é uma propriedade muito importante. Aqui estão dois exemplos de onde isso não é respeitado:

 #      $ gem install rails 

Parece bastante inofensivo, certo? Pense novamente, o que acontece quando você copia e cola isso na linha de comando? Você provavelmente receberá:

 bash: command not found: $ 

Um erro comum. Você deseja que o comando se pareça na linha de comando ou copie-o acidentalmente. Eu recomendaria desistir de $ . Você também pode encontrar uma maneira de proibir copiar e colar esse símbolo para que o erro não incomode os usuários.

Um exemplo mais recente: você verificou como é fácil destacar o código que o usuário deseja copiar?

Kelsey Hightower se esforçou para copiar o código de exemplo do StackOverflow na apresentação do Google Cloud Next.


“Bons programadores copiam, grandes programadores colam”

Ele fez isso de propósito? Nós nunca saberemos. No entanto, esta é uma ilustração de como os programadores tentam destacar grandes blocos de texto em alguns sites de documentação. Verifique se a interface do usuário do site facilita a cópia de grandes blocos. Você pode até quebrar esses blocos para explicar os fragmentos individualmente. Então eles se tornarão mais acessíveis para cópia e compreensão.

"Isso é tudo!"

"Isso é tudo!" A frase parece bastante inofensiva fora de contexto, mas imagine como certas palavras como "fácil", "simples", "trivial" e "descomplicada" são percebidas quando você tem problemas - não é ótimo! Quando uma pessoa fica paralisada tentando fazer a API funcionar, essa frase lança dúvidas sobre sua inteligência e faz com que ele faça a pergunta: "Então, eu sou estúpido?" Desmoraliza.

Simplificação excessiva

Simplificação é comum. É mais comum entre iniciantes na documentação escrita. Freqüentemente, os autores da documentação são, ao mesmo tempo, os desenvolvedores do sistema; portanto, algumas coisas parecem "fáceis" para eles. Mas eles desenvolveram essa função, escreveram código para ela, verificaram várias e muitas vezes e depois escreveram a documentação. Quando você faz algo dezenas de vezes, fica claro que será "fácil" para você. Mas e alguém que nunca viu uma interface do usuário ou função antes?

Empatia

A escolha das palavras realmente importa. Empatia é a capacidade de entender e compartilhar os sentimentos dos outros. Quando demonstramos empatia, ajudamos não apenas os novatos, mas também os usuários mais avançados. Isso ajuda a aumentar o número potencial de usuários, casos de uso, clientes e até a receita da empresa.

Mas quando a documentação é escrita por um desenvolvedor de projetos especializado, a empatia é mais difícil. Aqui estão algumas dicas úteis que me ajudaram no passado:

• Peça aos participantes menos experientes do projeto que comentem honestamente sobre a documentação.
• Incentive os participantes menos experientes do projeto a contribuir ou apontar para pontos de documentação que eles não entendem.
• Crie um ambiente em que as perguntas sejam encorajadas, incluindo aquelas que podem parecer "óbvias" para os participantes experientes do projeto - isso ajudará você a perceber "pontos cegos"
• Use processadores de código na revisão de código e nos processos de IC para garantir empatia e facilidade de idioma para todos os usuários.
• Por fim, solicite comentários sobre a documentação de usuários reais, mostre o texto e pergunte se está tudo claro

Mensagens de erro como um tipo de documentação

Normalmente, os usuários têm mais probabilidade de ver mensagens de erro do que documentação. Segundo Kate Voss, "as mensagens de erro são realmente uma oportunidade". Acredito que muitos desenvolvedores de documentação estão perdendo essa oportunidade. Há um lugar para treinamento, estabelecendo relações de confiança e expectativas dos usuários. Primeiro de tudo, você ajudará as pessoas a se ajudarem.

Kate em Write The Docs fornece muitas informações úteis sobre como escrever mensagens de erro. Aprendi muito durante o meu trabalho anterior sobre mensagens de erro da API, além de estar do outro lado das barricadas, recebendo mensagens de erro de outras APIs como desenvolvedor.

Kate diz que boas mensagens de erro são baseadas em três princípios:

• Modéstia
• Humanidade
• Utilidade

Modéstia

Você precisa se desculpar imediatamente, mesmo que não seja sua culpa. Eu também pratico isso no serviço de suporte.

Um exemplo:

Desculpe, não foi possível conectar a ___. Verifique suas configurações de rede, conecte-se a uma rede disponível e tente novamente.

Humanidade

Use termos legíveis por humanos; evite frases como "exceção lançada pelo alvo da chamada". Ao escrever um código para o qual muitas mensagens de erro são acionadas, é fácil manter um vocabulário claro.

Exemplo (erro de código de status do Twilio 401):

 { “code”: 20003, “detail”: “Your AccountSid or AuthToken was incorrect.”, “message”: “Authenticate”, “more_info”: “https://www.twilio.com/docs/errors/20003", “status”: 401 } 

Utilidade

Se você se lembra de uma dessas dicas, lembre-se da utilidade. Compartilhe informações com o usuário sobre como corrigir o problema.

Um exemplo:

Desculpe, a imagem que você tentou enviar é muito grande. Tente novamente com imagens menores que 4000 px de altura e 4000 px de largura.

Como escrever mensagens de erro

Como em qualquer outra documentação, forneça informações importantes primeiro. Isso pode ser feito especificando o objeto primeiro e depois a ação. O usuário está procurando um resultado, não como chegar lá. Isso é útil quando os usuários procuram rapidamente por mensagens de erro.

Mau exemplo:

Pressione o botão Voltar para retornar à página anterior.

Bom exemplo:

Para retornar à página anterior, use o botão Voltar.

Mensagens de erro da documentação

Acho muito útil quando mensagens de erro gerais da API são mencionadas na documentação. Dessa maneira, o autor da documentação pode esclarecer a mensagem de erro sem ampliar a documentação e, ao mesmo tempo, ajudar o usuário a entender por que o erro ocorre.

O Twilio publica um catálogo completo de erros e avisos com possíveis causas e soluções. Usando esse método, você pode tornar as mensagens de erro reais mais curtas, mas ainda úteis.

No caso do erro 20003 (erro do código de status 401, mencionado anteriormente), há muitos motivos possíveis que estão claramente indicados no catálogo.


Fonte: https://www.twilio.com/docs/api/errors

O Stripe faz algo semelhante com uma descrição detalhada dos vários códigos de erro.




Fonte: https://www.twilio.com/docs/api/errors

Você pode até encontrar suas mensagens de erro nas perguntas do StackOverflow. Responda a eles de maneira modesta, humana e com benefícios. Devido ao SEO, os usuários geralmente acabam recebendo suas mensagens de erro no StackOverflow, em vez da documentação real.

Dica: se alguém não respondeu modestamente, humanamente e com benefícios, com "reputação" suficiente, você pode editar as respostas do StackOverflow.

Seleção de palavras

Muitas palavras têm padrões mentais bem estabelecidos. Por exemplo, palavras como "bibliotecas", SDKs, "wrappers" e "clientes" já estão sobrecarregadas e passam pela atenção do leitor.

Em sua palestra, "Mesmo para esta palestra, é difícil encontrar um nome" em Write The Docs, Ruthie Bendor diz por que escolher as palavras certas pode ser tão difícil.

Costumamos escolher mal as palavras, embora, ao escrever texto, façamos isso o tempo todo. Como muitos títulos do SDK, cada palavra evoca uma ampla gama de sentimentos, idéias e definições no leitor. Você pode não entender isso - e frequentemente fazemos as suposições erradas.

Em tal situação, o famoso provérbio é verdadeiro como nunca antes: "Existem apenas duas tarefas difíceis no campo da ciência da computação: invalidação de cache e invenção de nomes". A citação é frequentemente creditada a Phil Carleton, mas hoje existem muitas variações desse ditado. Às vezes, no final, eles adicionam "... e um erro por unidade". Ruti considera isso uma demonstração de que o software hoje é amplamente baseado no código ou no trabalho de outra pessoa.

Por que nomes de objetos ruins (ou documentação) são preservados?

Como na simplificação excessiva, geralmente não entendemos que o nome é ruim. Isso é o que Ruthie chama de fracasso da empatia . É assim que se diz que o problema das palavras malsucedidas não me diz respeito e, portanto, não existe.

Dica para os EUA: Para evitar racismo acidental, use as palavras "lista proibida" e "lista permitida" em vez de "preto" e "branco".
(Fontes: Andre Staltz e trilhos / trilhos / questões / 33677 )

Ainda me lembra o que Ruthie chama de erro de pensamento iniciante . É como dizer: "Está completamente claro para mim. Não entendo como alguém não pode entender isso. "

Finalmente, Ruthie menciona um erro de localização . Por exemplo, a palavra Bing em chinês significa "doente".

De acordo com um estudo de pesquisa de código aberto do GitHub de 2017 :

Quase 25% dos desenvolvedores leem e escrevem inglês não é "muito bom". Ao se comunicar em um projeto, use um idioma compreensível e acessível para pessoas de países que não falam inglês.

Você leva isso em consideração ao usar americanismos e expressões idiomáticas na documentação? Muitos deles podem ser incompreensíveis para os usuários.

Dica: acredito firmemente que um dos maiores "truques" para resolver esses problemas é a diversidade da equipe de documentação.

Ainda existem casos em que reconhecemos um erro, mas não podemos ou não queremos corrigi-lo, porque ...

• Amarrado a ela
• Não encontramos tempo
• Não vemos a importância
• Não temos uma agência para consertá-lo.

Você pode dizer ou ouvir: “Mas essa é minha ideia!”, “Quem removeu meu amor?” "Se mudarmos o nome, tudo vai quebrar", "não acredito que a alteração desse nome afete algo importante."

Você não pode ter medo de refatorar e reescrever quando se trata de documentação. Como melhorá-lo, se você não concorda com o fato de que inicialmente não foi feita a melhor escolha?

Como escolher as palavras certas?

Para começar, recomendo fazer uma pergunta: que palavras seus usuários usam? Círculos de programadores diferentes usam termos diferentes, não tente usar outros. Isso é útil não apenas para os leitores, mas também para pesquisa e SEO.

No final, tudo inevitavelmente se resume à avaliação subjetiva. No entanto, existem alguns princípios a serem considerados. Ruthie diz que os nomes ruins são os que podem:

• embaraçar
• chatear
• enganar
• confundir
• ofender

Bons nomes, por outro lado:

• contribuir para esclarecimentos repentinos ("é isso!")
• injetado no contexto
• explicar
• iluminar
• fornecer suporte

Eu recomendo levar essas qualidades em consideração ao deduzir a documentação para fazer análises úteis e honestas sobre ela.

Escolher as palavras certas é difícil. Não existe uma fórmula mágica. Todos os usuários são diferentes, assim como os casos de uso do produto; o que funciona para alguns pode não funcionar para outros. Se fosse fácil, todos teriam uma documentação muito melhor. Como Ruthie diz aos desenvolvedores: “Escrever programas é um exercício para inventar nomes. Lide com isso. E se você estiver escrevendo documentação para o programa de outra pessoa, "informe ao desenvolvedor se o nome não atinge o alvo".