Dicas para escrever com competência a documentação técnica para os usuários.
Parte 1
Em um dos artigos anteriores, destacamos como ocorre o processo de
documentação e localização de nossos produtos .
Desta vez, este é o manual do
nosso escritor técnico Andrei Starovoitov, que ajudará a tornar sua documentação mais fácil e compreensível para os usuários (as técnicas descritas são usadas pela Apple, Microsoft e outras empresas para documentar seus produtos).
Como você sabe, uma boa documentação não é um luxo, mas um meio de aumentar as vendas da empresa. Se você iniciar ou já estiver desenvolvendo algum tipo de programa, para entrar no mercado mundial com ele, precisará de um manual do usuário (também conhecido como Guia do Usuário) ou de pelo menos um documento que indique aos clientes como começar a trabalhar com o seu produto (o chamado Começando com).
Em que idioma escrever a documentação - em russo e depois traduzi-la ou imediatamente em inglês - você decide. Na Parallels, escolhemos a segunda abordagem. Muitas vezes, é muito mais fácil fazer uma descrição em inglês, pois quase todos (e agora podemos dizer que "todos") termos de computador em russo são emprestados.
Mais adiante no texto, focaremos nos exemplos em russo e em inglês.
Então, o que você deve procurar ao escrever a documentação?
Tipos de tópicos na documentação
Ao escrever um tópico, primeiro você precisa determinar que tipo de tópico será :)
Isso dependerá do que e como escrever nele.
Existem
4 tipos principais de tópicos :
•
Tópicos que descrevem como resolver um problema específico ou várias tarefas relacionadas (em inglês, esse tipo de tópico é chamado de
páginas de tarefas) .
Por exemplo, "Instalar o Parallels Desktop" ou "Desligar ou pausar o Windows". Cada um desses tópicos descreve uma série de uma ou mais etapas que um usuário deve executar para atingir um objetivo específico. O manual do usuário consiste principalmente desses tópicos.
Geralmente, os usuários não gostam de ler, especialmente quando há muito texto. Portanto, você deve tentar tornar esses tópicos o mais curto possível. Idealmente, se as informações forem apresentadas da seguinte forma: “você pode fazer algo, basta clicar aqui e aqui” (os tópicos da tarefa serão discutidos em mais detalhes na próxima parte do artigo).
Se o desenvolvedor acredita que há alguma informação adicional que o usuário precisa conhecer e há muitas, isso é melhor descrito em tópicos conceituais (veja abaixo).
•
Tópicos conceituais (em inglês -
páginas conceituais ). Nesses tópicos, não há instruções sobre como resolver qualquer problema. Eles contêm informações que contribuem para uma maior compreensão das coisas. Por exemplo, os tópicos conceituais são usados para:
- Explique aos usuários exatamente como funciona qualquer processo;
- diga o que pode ser feito nas configurações do aplicativo;
- descreva os recursos adicionados na nova versão do produto;
- forneça informações adicionais que ajudarão o usuário a entender ou resolver melhor um problema.
Observe que informações adicionais (caso existam muitas) devem ser fornecidas precisamente no tópico conceitual para não sobrecarregar o tópico da tarefa.
•
Tópicos da Ajuda (em inglês -
páginas de referência ) - contêm informações às quais o usuário pode consultar periodicamente para descobrir o que um termo específico significa, como uma função funciona etc. Um bom exemplo desses tópicos é o dicionário no final do guia (também conhecido como Glossário). Os tópicos de referência são especialmente úteis para explicar a finalidade de vários elementos da interface.
•
Tópicos que descrevem como resolver um problema (em inglês -
páginas de solução de problemas ).
Por exemplo: "Não consigo ativar o Parallels Desktop" ou "Não consigo conectar-me à Internet". Estes tópicos descrevem o que precisa ser feito para resolver um problema. Eles também podem conter informações que ajudarão a entender qual é a causa do mau funcionamento.
Instruções básicas para todos os tipos de documentação
Ao criar um guia:
1)
Concentre-se no usuário
• Em vez de estruturar a descrição do produto com base em seus recursos ou elementos da interface, tente se concentrar nas tarefas que o usuário provavelmente tentará resolver.
Por exemplo, um tópico sobre como proteger dados em uma máquina virtual pode ser chamado de 2 maneiras:
a) "Configurações de segurança", que descreve em detalhes o que pode ser feito para proteger os dados.
b) Faça vários tópicos descrevendo tarefas específicas:
- “Proteja seus dados com software antivírus”
- “Faça backup da sua máquina virtual” (“Faça backup da sua máquina virtual”)
De acordo com as tendências atuais da documentação, a segunda abordagem é preferível, pois nesse caso o usuário não precisa adivinhar se deve ou não fazer alguma coisa e recebe instruções claras sobre o que exatamente precisa ser feito.
• Concentre-se nas tarefas do usuário e em seu nível de conhecimento técnico.
Por exemplo, na documentação para o usuário médio, em vez de escrever "Criar uma máquina virtual", você deve escrever "Instalar o Windows ou qualquer outro sistema operacional", como o termo " máquina virtual ”está longe de ser conhecida por todos. Ou outro exemplo - um tópico que descreve como criar atalhos de teclado rápidos, é melhor chamar "Configurar atalhos de teclado" em vez de "Configurações do teclado".
Embora qual seja o objetivo, para a maioria dos leitores de Habr seria mais claro "Configurar atalhos", mas a pergunta já é quanto esse termo é apropriado na terminologia oficial no momento :)
• Se isso não estiver claro, explique por que o usuário pode precisar concluir uma tarefa específica.
Por exemplo:
• Ao descrever, tente usar as palavras que o usuário usa todos os dias em seu discurso. Se um termo tecnicamente complexo puder ser substituído por palavras mais simples, tente sempre usar palavras mais simples.
Por exemplo, "transparente" em vez de "transparente". Se você der um exemplo do idioma inglês, use "use" em vez de "utilize".
2)
Tente fornecer todas as informações necessárias sem palavras desnecessárias“Embaixadores da ilha de Samos vieram a Esparta para pedir ajuda. Eles fizeram um discurso longo e bonito. Os espartanos disseram: "Depois de ouvir o fim, esquecemos o começo e, esquecendo o começo, não entendemos o fim". Samosets foram perspicazes. No dia seguinte, eles chegaram à reunião com uma sacola vazia e disseram apenas quatro palavras: "Há uma sacola, não há farinha". Os espartanos os repreenderam - duas palavras foram suficientes: "não há farinha", mas ficaram satisfeitos com o raciocínio tão rápido e prometeram ajudar.Se você descrever a funcionalidade por muito tempo - ninguém a lerá. Mas também é completamente "espartano", porque, se muito pouco for escrito, haverá perguntas e dúvidas, os usuários começarão a atrair a equipe de suporte. Em geral, é importante manter o equilíbrio.
Para ajudar os usuários a encontrar todas as informações necessárias e, ao mesmo tempo, descrever cada seção o mais brevemente possível:
- Concentre-se nas informações mais importantes necessárias para resolver o problema descrito no tópico. Se alguns detalhes não forem necessários para a tarefa, não os descreva.
- Não há necessidade de documentar cada clique. Se tudo estiver claro na interface, deixe o usuário descobrir por si mesmo. Por exemplo, em vez de documentar cada etapa da instalação do programa, é melhor escrever: "Para instalar o programa, siga as instruções na tela". Se, como o último estágio de um procedimento, você precisar clicar em OK, isso também não vale a pena descrever.
- Em vez de fornecer todas as informações em um tópico, mostre ao usuário onde você pode ler informações adicionais usando links para outros tópicos, links para recursos externos ou insira no final a seção "Informações relacionadas", que conterá links para tópicos relacionados ao que é descrito na tela.
- Se uma tarefa longa puder ser dividida em vários estágios ou subtarefas, cada um dos quais é uma tarefa separada, divida o tópico nas seções apropriadas ou crie uma seção no guia, que consiste em tópicos que descrevem cada estágio. Nesse caso, não se esqueça de inserir links para tópicos relacionados.
- Se uma tarefa (por exemplo, iniciar uma máquina virtual) puder ser executada de várias maneiras, não há necessidade de descrever todas elas. Basta mencionar a maneira mais rápida e fácil. Se você ainda acha útil conhecer outros métodos, descreva-os no tópico final (em inglês - Outro).
3)
Não repita a mesma informação nas páginas
Em vez de repetir informações em cada tópico que já está descrito em outro tópico, é melhor referir que uma descrição mais detalhada pode ser encontrada em um tópico ou simplesmente fornecer um link para ele.
4)
Atraia a atenção do usuário corretamente
Quando a descrição precisa atrair a atenção do usuário, as seguintes palavras introdutórias são usadas - "Atenção!" (em inglês - Aviso!), "Importante:" (em inglês - Importante :) e "Nota:" (em inglês - Nota :).
Cada uma dessas palavras implica seu próprio nível de "importância".
Para não sobrecarregar o usuário em vão, use cada termo corretamente:
- Atenção! (Aviso! Em inglês) para indicar uma situação perigosa que, se não for evitada, poderá resultar em perda de dados, danos aos componentes ou qualquer outro dano.
- Use "Importante:" (em inglês - Importante :) para indicar uma situação significativa e potencialmente problemática que, no entanto, não pode levar a danos físicos, danos ou perda de dados.
- Use “Nota:” (Nota :) para fornecer qualquer informação adicional relacionada a este tópico. Embora essa inserção desanexe usuários da tarefa atual, ela pode ser útil.
Por exemplo:
Para abrir a configuração da máquina virtual, clique em Ações> Configurar.
Nota: A máquina virtual deve estar desligada.
Use a nota “Nota:” com moderação - se você a inserir com muita frequência, ela obstrui o texto e deixa de prestar atenção.
Se possível, insira “Atenção!”, “Importante:” e “Nota:” no início do tópico, para que o usuário descubra isso antes de começar a executar qualquer procedimento. No entanto, se as informações se referirem apenas a uma etapa específica, insira-a após esta etapa.
Um exemplo:
Para continuar ...(na próxima parte do artigo, discutiremos mais detalhadamente tópicos que descrevem como resolver um problema específico)