Mau conselho: como escrever documentação técnica? Parte dois

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

Continuaçã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.

Você pode ler o início do artigo aqui , mas descrevemos o processo de documentação e localização de nossos produtos, anteriormente neste artigo .

Nesta parte, analisaremos detalhadamente os tópicos que consistem principalmente na documentação do usuário (especialmente o Guia do Usuário) - ou seja, tópicos de tarefas que descrevem como resolver um problema específico.



Quantas tarefas descrever no tópico - uma ou mais?

Um tópico de tarefa pode descrever uma tarefa - "Iniciar um aplicativo do Windows" ("Iniciar um aplicativo do Windows"), bem como várias tarefas relacionadas. Por exemplo, o tópico “Otimizar desempenho” pode consistir nas seguintes seções: “Economizar espaço em disco automaticamente” e “Ajustar o seu MacBook para obter melhor desempenho ou economizar bateria” (“Otimizar seu MacBook para maior autonomia da bateria ou melhor desempenho ”).

Devemos tentar escrever tópicos de tarefas sobre o princípio: um tópico - uma tarefa. É verdade que há uma exceção - se você tiver duas tarefas opostas em ação, elas deverão ser descritas em um tópico. Por exemplo, se você precisar descrever como alternar a máquina virtual para o modo de tela cheia e como sair mais tarde, faça isso dentro do mesmo tópico.
Se você precisar descrever várias tarefas relacionadas, isso também poderá ser feito em um tópico, desde que a descrição não seja longa.

Seções de tópicos de tarefas

Os tópicos da tarefa consistem em:

• Título
• Parte introdutória (em inglês "introdução")
• Frases, o que leva a uma descrição do que exatamente o usuário precisa fazer (em inglês, "cabeçalho da etapa")
• Numeradas ou iniciando em etapas grandes de ponto (em inglês “etapas numeradas ou com marcadores”)
• A parte final (em inglês “outro”)

Às vezes acontece que o tópico da tarefa não contém todas as seções acima - por exemplo, não há necessidade de inserir Introdução ou Outro. Além disso, abordaremos mais detalhadamente cada seção do tópico.

Manchete

Devemos tentar criar esses cabeçalhos para que o usuário entenda imediatamente o que será escrito no tópico.

Torne as manchetes amplas, mas não muito longas ao mesmo tempo. Cabeçalhos longos podem não ser totalmente exibidos em alguns navegadores ou no Apple Help Viewer.

Ao escrever um título, use o imperativo ("Faça isso")

Por exemplo, “Configurar uma impressora usando o Bonjour”.

Não use o imperativo nos nomes dos tópicos que não descrevem como resolver um problema.

Use palavras amigáveis ​​no nome do tópico, não se concentre nos elementos da interface.

O usuário não deseja entender os recursos, termos, elementos da interface etc. - ele precisa resolver seu problema específico. Portanto, no nome do tópico, tente usar as palavras que o próprio usuário usaria. Por exemplo, se você chamar o tópico "Configurar o Mac para usar aplicativos do Windows", será muito mais compreensível para o usuário do que o tópico "Sobre máquinas virtuais".

Tente formular o objetivo como o usuário provavelmente faria. Por exemplo, em vez de "Iniciar uma sessão remota" - nomeie melhor o tópico "Iniciar o controle remoto do Windows".

Se você precisar usar termos ou nomes de interface tecnicamente complexos, é melhor fazer isso não no cabeçalho, mas na introdução do tópico.

Se você estiver escrevendo documentação em inglês, as palavras no título devem começar com uma letra maiúscula

Direita : Configure o seu Mac para usar aplicativos do Windows

Errado : configure o seu Mac para usar aplicativos do Windows

(Discutiremos a capitalização do cabeçalho em mais detalhes na próxima parte do manual).

Introdução (Introdução)

Na parte introdutória, que segue imediatamente após o cabeçalho, você deve escrever o que o usuário precisa saber antes de começar a executar a tarefa.

O prólogo pode conter:

• Informações gerais adicionais: o que o usuário pode fazer.
• Motivação : por que o usuário pode precisar executar uma ou outra ação. Aqui está um exemplo de parte introdutória que descreve por que você pode precisar baixar e usar máquinas virtuais prontas:

Use máquinas virtuais prontas para uso

Se você não tiver tempo para criar uma nova máquina virtual com a configuração necessária, poderá fazer o download da máquina virtual finalizada com uma configuração pré-configurada.

• Avisos sobre qualquer possível dano ao hardware, software ou perda de dados que podem ocorrer enquanto o usuário executa uma ação.
• Informações importantes sobre possíveis problemas ou dificuldades que, embora não resultem em danos à saúde, equipamentos ou perda de dados, podem ocorrer durante a execução de uma tarefa.
• Explicação: o que esse ou aquele termo significa ou como qualquer recurso funciona.

Por exemplo, se um usuário do Parallels Desktop quiser trabalhar com o macOS e o Windows ao mesmo tempo, como se fosse um sistema operacional, na parte introdutória você poderá falar sobre o "Modo de coerência" para preparar o usuário para termos que será mais usado no tópico.

• Informações sobre condições adicionais : por exemplo, no tópico que descreve como conectar a impressora via Bonjour, a introdução pode informar quais versões do Windows oferecem suporte ao Bonjour.
• Condições necessárias para a tarefa atual : se antes de começar a executar as tarefas descritas no tópico, o usuário precisar executar ou verificar outra coisa, isso deve ser mencionado na parte introdutória. E seria bom fornecer links para tópicos onde está descrito, para que o usuário possa encontrar e ler rapidamente.

Não insira o prólogo onde não for necessário.

Embora a parte introdutória forneça informações úteis adicionais, às vezes tudo fica claro no próprio título. Nesses casos, você não precisa apresentar um texto introdutório, se for o caso.

Por exemplo:

Inicie aplicativos Mac através do menu Iniciar

Abra o menu Iniciar do Windows e siga um destes procedimentos:

• Clique em Todos os Programas> Aplicativos Compartilhados Parallels e selecione o aplicativo que deseja.
• Digite o nome do aplicativo no campo de pesquisa e selecione o aplicativo desejado nas opções propostas.

Não faça o prólogo muito longo

A introdução é muito longa para irritar o usuário. Nesses casos, os usuários costumam ignorá-lo e ir diretamente para a lista de etapas específicas.

Se a parte introdutória for muito grande, é necessário mencionar a principal e vincular uma página conceitual ou página de referência separada, na qual tudo já será descrito em detalhes.

Às vezes, para facilitar visualmente a leitura de textos longos na parte introdutória, marcadores podem ser usados. Por exemplo:



Não diga na introdução como concluir a tarefa

O prólogo não é para isso. O que precisa ser feito, onde e como - é necessário descrever apenas mais tarde, após a introdução.

No entanto, em casos raros, pode ser necessário informar aos usuários o que eles precisam para concluir a tarefa. No exemplo abaixo, a parte introdutória informa aos usuários o que eles precisam para concluir a tarefa descrita no tópico.



Não descreva os resultados da tarefa na parte introdutória.

Isso deve ser feito na parte final ( Outro ).

A frase antes das instruções (cabeçalho da etapa)

Após o Intro, você precisa inserir uma frase "introdutória" (em inglês - "cabeçalho da etapa"), que leva o usuário a instruções: o que exatamente precisa ser feito para alcançar um ou outro resultado.

Por exemplo, no Intro, escrevemos: “ Se você tiver um disco de instalação e uma chave de ativação, poderá usá-los para instalar o Windows em uma máquina virtual. "

Após o Intro, é apresentado o passo: " Para instalar o Windows: "

E então os próprios passos:

1) Clique aqui.
2) Escolha isso.
3) E assim por diante ...

Observação: se não houver Introdução no tópico, o cabeçalho da etapa é opcional.

Se o tópico descreve etapas seqüenciais, o cabeçalho da etapa deve se parecer com " Fazer algo:" ("Executar X:").
Por exemplo: “Para alternar para o modo de tela cheia:” (“Para iniciar o Windows:”) ou “ Para alternar para o modo de tela inteira:” .

Não se esqueça de colocar dois pontos no final

Se o cabeçalho usar palavras amigáveis, e você precisar usar termos técnicos complexos ou os nomes dos elementos da interface nas instruções, faça o seguinte: na parte introdutória, você explica o que o termo significa e, no cabeçalho da etapa, você já o usa ativamente.

Por exemplo:

1) deixamos o cabeçalho mais claro para o usuário:

“ Configure o Windows para ocupar a tela inteira”

2) A seguir, na introdução, apresentamos o termo "modo de tela cheia".

3) Depois disso, no cabeçalho da etapa você já pode usar o termo sem medo de que não seja compreensível para o usuário:

“ Para entrar em tela cheia:” (“Para entrar em tela cheia:”)

Se as etapas descritas no tópico não são uma sequência de ações, mas várias maneiras de atingir a meta, o cabeçalho da etapa deve ser executado da seguinte maneira: “Aqui estão algumas maneiras de fazer algo:” (“Aqui estão algumas maneiras de executar X:”) ou “ Para fazer isso, siga um destes procedimentos: ” (“ Para executar o X, siga um destes procedimentos: ”).

Por exemplo, “Aqui estão algumas maneiras de desligar o Windows:”) ou “ Para conectar uma impressora, siga um destes procedimentos: ” (“Para conectar uma impressora, siga um destes procedimentos: ”).

Ao criar o cabeçalho da etapa, você precisa usar as palavras que refletem a tarefa descrita no tópico da tarefa. Aqui estão alguns exemplos em inglês:

Título da página : Instale o Windows a partir de um disco de instalação.
Capas de tarefas : Instalando o Windows usando um disco de instalação.
Título da etapa : Para instalar o Windows.

Título da página : Ajustar configurações de coerência.
Capas de tarefas : Personalizando como o Windows aparece e se comporta no modo Coherence.
Título da etapa: Para personalizar o modo Coherence.

Título da página : Defina o Windows para ocupar a tela inteira
Capas de tarefas : Entrando no modo de tela cheia.
Título da etapa : Para entrar no modo de tela cheia, siga um destes procedimentos:

Etapas numeradas

Todos os tópicos que descrevem como executar uma tarefa específica contêm instruções sobre o que fazer. Essas ações no texto geralmente são numeradas (se for uma série de etapas consecutivas) ou destacadas por marcadores (se for proposto escolher uma das listas a seu critério).

Mantenha a lista das etapas necessárias o mais curta possível.

Escolha e descreva a maneira mais fácil e rápida de concluir uma ação. Métodos alternativos podem ser descritos na parte final (Outro) ou em outro tópico da tarefa. Não force o usuário a ler as instruções em 4 etapas, se for possível fazer o mesmo clicando em um botão.

Se a maneira mais fácil é executar a ação através da barra de ferramentas, descreva esta opção. Se a barra de ferramentas puder ser personalizada ao seu gosto e você tiver dúvidas, de repente a configuração da barra de ferramentas do usuário difere da descrita no tópico, descreva tudo como é feito com as configurações padrão. Como mostra a prática, a maioria dos usuários comuns raramente altera as configurações de "fábrica".

Se você precisar descrever várias maneiras de como executar uma ação em um tópico :

Se, em muitos tópicos de tarefas do seu livro, se repetir uma determinada ação que pode ser executada de maneiras diferentes (por exemplo, através de um menu ou barra de ferramentas), selecione um método e mencione-o sequencialmente em cada tópico da tarefa.

Se houver uma maneira alternativa simples e curta, e você certamente quiser falar sobre isso, poderá fazê-lo na mesma etapa.

Por exemplo: “Para abrir a configuração da máquina virtual, escolha Ações> Configurar ou clique no ícone Configurar no canto superior direito.”).

Numere as etapas a serem executadas sequencialmente.

Para não inflar a descrição e não destacar instruções muito curtas em etapas separadas (como “Clique em OK”), você pode combinar duas ações relacionadas e relacionadas em uma etapa, conforme mostrado abaixo:



Use marcadores para destacar ações inconsistentes

Às vezes, são oferecidas ao usuário várias maneiras de escolher como atingir a meta. Nesses casos, as opções propostas emitem marcadores.

Por exemplo:


Se a lista contiver os nomes dos elementos gráficos, destaque-os para maior clareza em negrito

Se a ação a ser executada pelo usuário listar vários elementos da interface gráfica (itens de menu, daws, etc.), inicie cada opção em uma nova linha, destacando o nome do elemento em negrito. Após o elemento marcado em negrito, coloque dois pontos e explique a descrição em texto sem formatação.

Como mostrado neste exemplo:


Se o texto no tópico se referir a vários elementos da interface várias vezes, pode valer a pena criar um tópico de ajuda separado, no qual esses elementos serão descritos.

Isso será especialmente útil se muitos tópicos do guia se referirem aos mesmos elementos. Nesse caso, no início do tópico, você deve fornecer um link para o tópico de referência no qual o elemento mencionado é explicado.

Se esse elemento for mencionado novamente mais adiante no texto, você não precisará mais fornecer um link para ele - apenas um no início. Quando há muitos links no tópico, isso pode complicar a percepção e a compreensão do que está escrito.

A parte final (Outro)

Outro é a informação final que vem após as etapas numeradas. Tente reduzir a parte final - use no máximo 3 parágrafos, cada um dos quais consistindo em no máximo 3 sentenças.

Use Outro para descrever os resultados ou consequências dessas ações.

Um exemplo de resultado ou consequência pode ser:

• Informações sobre onde os arquivos foram instalados;

• Aparece uma mensagem que exigirá ações adicionais do usuário;

• Configurações que o usuário precisará alterar após a conclusão das ações descritas.

Por exemplo, a parte final do tópico sobre como fazer o Parallels Access funcionar apenas em Wi-Fi, diz o seguinte: “ Se você configurou o Parallels Access para funcionar apenas em Wi-Fi e nenhuma rede sem fio é detectada no momento, uma mensagem é exibida. - Você gostaria de se conectar via 3G? "

Na parte final do tópico, você pode descrever uma maneira alternativa de concluir a tarefa.

Se o método alternativo puder ser descrito em uma frase, você poderá fazer isso na parte final do tópico.

Outro pode fornecer mais informações relacionadas à tarefa atual.

Essas informações podem informar aos usuários o que mais eles podem fazer após concluir a tarefa descrita.

No exemplo a seguir, o tópico descreve como encontrar um arquivo de uma máquina virtual no macOS Finder. E na parte final do tópico descreve o que mais o usuário pode fazer com o arquivo após a localização do arquivo.



Em Outro, você pode descrever informações adicionais que apenas alguns usuários precisam.

Por exemplo, na parte final do tópico sobre a integração de máquinas virtuais Windows no macOS, você pode escrever o seguinte: “Se você possui um MacBook Pro 2016 ou posterior, pode trabalhar com alguns aplicativos Windows usando a barra de toque”


Divida tarefas longas em estágios curtos

Basicamente, os tópicos da tarefa são curtos e cabem em uma página. No entanto, se for descrita uma tarefa complexa e muito longa, que pode ser dividida em estágios, estágios e procedimentos, vale a pena separar logicamente as informações e descrever cada estágio em um tópico separado, para que a descrição pareça mais simples, melhor lida e compreendida.

A seguir, é apresentado um exemplo do conteúdo do Guia do usuário do Parallels Desktop. A captura de tela mostra um capítulo que descreve várias maneiras de instalar o Windows em uma máquina virtual. E uma das maneiras - como importar dados de um computador remoto - é dividida em vários tópicos.



Para continuar ...

(na próxima parte, falaremos mais sobre tópicos conceituais e de referência e tópicos que ajudam a resolver problemas)