Mau conselho: como escrever documentação técnica? Parte Três e Última

Dicas para escrever com competência a documentação técnica para os usuários.
Parte 3 (final)

A conclusão do manual do nosso escritor técnico Andrei Starovoitov , que ajudará a tornar a documentação do usuário mais fácil e compreensível.



Desta vez, consideraremos com mais detalhes:

• tópicos conceituais (páginas conceituais);
• tópicos de referência (páginas de referência);
• tópicos que explicam como resolver um problema (páginas de solução de problemas);
• onde e como usar as capturas de tela;
• e também dê algumas dicas para quem escreve documentação em inglês.

Partes anteriores: nossa abordagem para documentação e localização; dicas de documentação parte 1 e parte 2 .

Tópicos conceituais (páginas conceituais)

Esses tópicos são necessários para fornecer aos usuários informações técnicas adicionais e, assim, não sobrecarregar o tópico da tarefa.

Observe que eles devem conter exatamente informações adicionais, mas não uma maneira de resolver o problema.

É bom usar tópicos conceituais para:

• diga como um processo específico funciona;
• Descreva quais novos recursos foram adicionados nesta versão do produto;
• fornecer ao usuário informações adicionais que o ajudarão a tomar uma decisão;
• Diga o que o usuário pode fazer no seu aplicativo.

Por exemplo, o tópico "Sobre máquinas virtuais" pode descrever o que é e como funciona. Mas este tópico não deve conter instruções sobre como criar uma máquina virtual - isso deve ser descrito no tópico da tarefa.

Assim, um usuário experiente, enquanto lê um tópico de tarefa, não reclama: "Por que você me pinta o que é, eu já sei ...". E quem não souber verá um link para um tópico conceitual e lerá.

Normalmente, os títulos dos tópicos conceituais começam com:

• “Sobre (algo)” (“Sobre Máquinas Virtuais”);
• "O que é ...?" ("O que é uma máquina virtual?");
• "Como isso funciona (algo)?" ("Como uma máquina virtual funciona?");
• “Compreendendo os conceitos básicos de máquinas virtuais” etc.

Aqui está um exemplo de um tópico conceitual da documentação em inglês:



Tópicos de referência (páginas de referência) :

Esses tópicos descrevem várias informações de referência às quais o usuário pode consultar, se necessário.

Bons exemplos de tais tópicos são:

• “Glossário” no final do guia;
• um tópico no qual você descreve quais itens estão disponíveis no menu e o que eles fazem, quais atalhos de teclado você pode usar ao trabalhar com o programa, quais ícones estão disponíveis na barra de tarefas etc.

Aqui está um exemplo de um tópico que descreve os ícones da GUI:



Tópicos que descrevem como resolver um problema (páginas de solução de problemas)


Esses tópicos ajudam o usuário a superar um obstáculo ou resolver um problema. Os tópicos de solução de problemas podem ter os seguintes cenários:

• O usuário tem um problema e deseja resolvê-lo. Por exemplo, "Meu dispositivo USB não funciona em uma máquina virtual".
• O usuário tentou fazer algo e falhou. Por exemplo, "Não consigo ativar o Parallels Desktop" ("Não consigo ativar o Parallels Desktop").
• Há alguma condição ou condição que o usuário deseja alterar. Por exemplo, "O Windows está lento" ("O Windows parece lento").

O que é e não está solucionando problemas :

Se o usuário quiser fazer algo, mas não souber como, isso deve ser descrito não na solução de problemas, mas no tópico da tarefa.

A solução de problemas implica que o usuário tentou fazer algo (de acordo com as instruções do tópico da tarefa), mas houve algum problema e o usuário não sabe como resolvê-lo.

Por exemplo, um tópico que descreve como usar uma unidade externa em um sistema operacional convidado é um tópico de tarefa.

E o tópico que descreve os possíveis problemas - "Estou tendo problemas para conectar um disco rígido" - é um tópico de solução de problemas. Seu conteúdo implica que o usuário seguiu as instruções, mas por algum motivo ele não teve êxito.

Se você escrever um tópico de tarefa e alguma etapa das instruções puder causar pequenas dificuldades, será permitido descrevê-lo na mesma etapa ou tópico. Para pequenas dificuldades, não é necessário escrever um tópico de solução de problemas separado.

Por exemplo, no final do tópico que descreve como alterar os atalhos do teclado, você pode adicionar: “Algumas combinações de teclas não podem ser editadas ou excluídas”.

Tópicos de solução de problemas

Normalmente, os tópicos de solução de problemas têm uma estrutura semelhante aos tópicos da tarefa.

Eles consistem em:

• Título ("título")
• Parte introdutória ("introdução")
• Frase introdutória, após a qual as etapas numeradas ou as informações necessárias ("cabeçalho da etapa") começam
• Informações necessárias para resolver um problema ("etapas para solução")
• A parte final (“outro”)

Título (título da página)

É bom quando o cabeçalho do tópico de solução de problemas expressa o problema em primeira pessoa do usuário. Por exemplo:

• “Não consigo ativar o Parallels Desktop” (“Não consigo ativar o Parallels Desktop”)
• "O Windows está lento" ("O Windows parece lento")
• "Uma mensagem diz 'Nenhuma máquina virtual detectada'" aparece

Se você está escrevendo documentação em inglês, deve usar letras maiúsculas no título (para letras maiúsculas, consulte os detalhes no final do artigo):

Direita: Meu dispositivo USB não está funcionando

Errado: meu dispositivo USB não está funcionando

Introdução (introdução)

Imediatamente após o cabeçalho, forneça aos usuários as informações que eles precisam saber primeiro.

Por exemplo:

• Explique a causa mais provável do problema. Se houver muitas razões, descreva tudo possível.
• Às vezes, você pode descrever em termos gerais o que precisa ser feito para resolver um problema. É geralmente - instruções detalhadas devem ser fornecidas nas etapas da solução.

Frase introdutória (cabeçalho da etapa)

Antes da sequência de etapas que você precisa executar para resolver o problema, escreva uma frase introdutória. Não se esqueça de colocar dois pontos no final.

Se a solução para o problema for uma série de ações seqüenciais:

Nesses casos, a frase introdutória deve ser realizada de acordo com os mesmos princípios dos tópicos da tarefa (consulte a segunda parte das dicas), ou seja, use as mesmas palavras da formulação da tarefa.

Por exemplo, você escreve um tópico de solução de problemas no qual explica por que o usuário não pode abrir a configuração da máquina virtual (o item de menu fica acinzentado e inativo):

Título: “Não consigo abrir as configurações da máquina virtual”

Introdução: “Se você não pode abrir as configurações da máquina virtual (o item de menu está acinzentado), o motivo mais provável é que a máquina virtual não está desligada.”

Além disso, a frase introdutória: “Para abrir as configurações da máquina virtual:” (as mesmas palavras são usadas nesta frase e na formulação da tarefa a ser executada)

E então as etapas - 1) Verifique se a máquina está desligada. Se funcionar, clique aqui e ali. 2) Então faça isso.

Se o problema tiver várias soluções:

Nesses casos, a frase introdutória deve conter as palavras:

- "experimente estas soluções",
- "tente o seguinte",
- "certifique-se disso", etc.

Aqui estão alguns exemplos da documentação em inglês:

Título da página: Não consigo ativar o Parallels Desktop
Capas de tarefas: uma lista de itens a serem verificados
Cabeçalho da etapa: se estiver com problemas para ativar o Parallels Desktop, verifique se ...

Título da página: Windows parece lento
Capas de tarefas: uma lista de itens a serem testados
Cabeçalho da etapa: se o desempenho do Windows parecer lento, tente o seguinte ...

Título da página: Uma mensagem diz "Não há Macs conectados"
Capas de tarefas: várias coisas para verificar ou tentar
Cabeçalho da etapa: se você não encontrar o seu Mac na lista de Macs

Informações necessárias para resolver o problema (etapas para solução)

Esta seção inclui tudo o que o usuário precisa saber e / ou realizar.

Se houver várias soluções:
Nesses casos, descreva cada método usando marcadores (mais sobre isso na segunda parte das dicas). Se algum método for complicado e você já o descreveu em detalhes em outro tópico, basta fornecer um link.

Se o que você precisa fazer já está descrito em algum outro tópico:
Basta dar um link para este tópico.

Se não houver instruções específicas, o que poderia ser feito para resolver o problema:
Forneça informações adicionais que possam ajudar o usuário a descobrir o que pode estar causando o problema.

Conclusão (outro)

Em conclusão, você pode fornecer informações adicionais relacionadas à tarefa ou possíveis soluções para o problema. Você pode ler mais sobre como usar outro na parte dois das dicas .

Usando gráficos (capturas de tela, gráficos, diagramas etc.)

Capturas de tela e diagramas podem ajudar os usuários a entender melhor o que está escrito no tópico.

Quando usar gráficos:

Em cada etapa, você não precisa inserir uma captura de tela - o usuário simplesmente não sabe para onde procurar, comparando constantemente a tela e a captura de tela.

As capturas de tela devem ser inseridas quando elas ajudarem significativamente a entender o que está escrito nas instruções.

Por exemplo:

• Quando você precisa mostrar um botão ou ícone que não tem nome no gua, ou que não chama a atenção imediatamente, ou existem vários similares na tela;
• Quando você precisar fornecer um contexto para a tarefa ou uma explicação visual clara de como e como ela será no final;
• Se a captura de tela permitir que você entenda ou explique rapidamente algo que exigirá explicações longas e complicadas em palavras.

Onde e como colocar a programação:

Abaixo estão algumas recomendações sobre onde e como colocar gráficos na página.

1) Se a captura de tela refletir as informações conceituais ou o resultado da tarefa, você poderá inseri-las na introdução ou após a introdução.

Aqui está um exemplo da documentação em inglês, que mostra um tópico que descreve o modo de janela do Windows. Uma captura de tela que mostra o que acontecerá após a inserção de um comutador após a introdução e antes da própria instrução, como alternar para este modo:



2) Se a captura de tela se referir a uma etapa específica nas instruções, insira-a após ou dentro desta etapa:



Se você precisar inserir uma captura de tela de um botão, ícone ou outro elemento da interface, precisará inseri-lo após o nome desse elemento:



Não use gráficos para ilustrar coisas óbvias.

Especificamente, não use capturas de tela para ilustrar:

• Menu
• Ícones, botões e guias que têm um nome
• Tudo o mais que pode ser fácil e facilmente descrito em palavras.

Dicas adicionais para quem escreve documentação em inglês:


1) Como capitalizar títulos:

letras maiúsculas Três estilos de letras maiúsculas estão disponíveis: estilo de frase, estilo de título e todas as maiúsculas.

• Letras maiúsculas no estilo da frase: Esta linha fornece um exemplo de letras maiúsculas no estilo da frase.
• Letras maiúsculas no estilo do título: Esta linha fornece um exemplo de letras maiúsculas no estilo do título.
• Todas as maiúsculas: ESTA LINHA FORNECE UM EXEMPLO DE TODAS AS CAPS.

Não use todas as letras maiúsculas para enfatizar.

letras maiúsculas (estilo de frase): ao usar letras maiúsculas no estilo de frase, coloque em maiúscula a primeira letra da primeira palavra, bem como a primeira letra de quaisquer nomes próprios e adjetivos adequados.
letras maiúsculas (estilo de título): Use letras maiúsculas no estilo de título para títulos de livros, títulos de peças, títulos de capítulos e títulos de seções (cabeçalho do texto).

Siga estas regras ao usar maiúsculas no estilo de título. Coloque em maiúscula todas as palavras, exceto:

• Artigos (a, an, the), a menos que um artigo seja a primeira palavra ou siga dois pontos
• Conjunções de coordenação (e, mas, ou, nem, para, ainda, e assim)
• A palavra para em infinitivos (Como conectar sua impressora)
• A palavra como, independentemente da parte do discurso
• Palavras que sempre começam com uma letra minúscula, como iPhone e iPad.
• Preposições de quatro letras ou menos (at, by, for, from, in, into, of, off, on, into, out, over, to, up e with), exceto quando a palavra faz parte de uma frase verbal. Por exemplo:
  
  Iniciar o ComputerLog
  Para o ServerGet
  Iniciado com o Parallels Desktop

Capitalizar:

• A primeira e a última palavra, independentemente da parte do discurso:
Para usuários Linux

Para que servem as ferramentas Parallels

• A segunda palavra em um composto hifenizado:

Correto: Eventos de alto nível, endereçamento de 32 bits
Incorreto: eventos de alto nível, endereçamento de 32 bits
Exceções: embutido, plug-in

• As palavras são, se, é, é, então, isso e isto

2) Como usar a palavra "clique":

click Use click para descrever o ato de posicionar o ponteiro em um objeto na tela e pressionar e soltar brevemente o botão do mouse. Não use o clique. Como a maioria dos usuários sabe o que é clicar, é necessário defini-lo apenas na documentação projetada para usuários iniciantes, como tutoriais.
Correto: Clique em Mac se desejar usar o dispositivo USB com o Mac OS X.

Incorreto: aponte para Mac e clique nele se desejar usar o dispositivo USB no Mac OS X.
clique em Não use; use clique.

3) E-mail ou e-mail?

Use email. Não use email.

4) Se ou se?

Use if para expressar uma condição. Use se deseja expressar alternativas.
Correto: verifique se o Parallels Tools foi instalado.
Incorreto: verifique se o Parallels Tools foi instalado.
Correto: Clique em Mac se desejar usar o dispositivo USB com o Mac OS X.

5) Como usar nomes de produtos:

Siga o estilo de capitalização na embalagem do produto. Use o nome completo do produto para sua primeira ocorrência em uma seção de texto (por exemplo, um capítulo). Depois disso, quando aplicável, use uma versão abreviada do nome do produto.

Por exemplo: Parallels Desktop 14 para Mac: na primeira ocorrência em uma seção de texto, use o Parallels Desktop 14 para Mac.

Nas ocorrências subsequentes, use o Parallels Desktop.

Conclusão

Nestas três partes do manual, tentamos reunir, resumir e estruturar as dicas que ajudarão a tornar sua documentação mais fácil e compreensível.

Não insistimos que a escrita seja necessária dessa maneira - existem muitas abordagens para documentação e técnicas. Olhe para a configuração e use as que mais lhe agradam.

Muito obrigado pela sua atenção e interesse!