Exemplo de um aviso de edição

Se você lista marcas registradas e como você as menciona é domínio dos advogados da empresa. Em qualquer caso, você lista apenas aqueles nomes de produtos com marca registrada que aparecem naquele guia do usuário em particular.

Na maioria das vezes, as marcas registradas são indicadas:

• no aviso de edição (como a ilustração acima mostra)
• em uma seção separada em algum lugar no guia do usuário

mencione essa nota

Se os advogados corporativos desejam que cada ocorrência de um nome de produto registrado como marca seja indicada com um asterisco ou nota de rodapé, tente convencê-los a desistir desse fiasco de design de página. Poluir o texto com asteriscos ou números de notas de rodapé é distrativo para os leitores.

As garantias acompanham produtos de hardware físico—não software. Advogados corporativos assumem a responsabilidade pela linguagem e formato da garantia. Se você estiver criando um guia ou livro de exemplo para seu portfólio, pode usar este "exemplo de garantia" anônimo.popup para mostrar que você está ciente de que as garantias devem ser incluídas.

Os produtos de hardware geralmente têm uma seção de avisos de segurança no início de seus manuais. Esses avisos podem aparecer como uma subseção do prefácio, por exemplo, ou como uma seção separada por direito próprio. Essas seções geralmente reúnem todos os avisos de perigo, advertência e cautela que ocorrem ao longo do livro e os organizam de alguma forma lógica. Mas mesmo com esse alerta antecipado, os livros de hardware ainda colocam os avisos individuais nos pontos onde se aplicam. (Para mais informações, veja avisos especiais.)

Livros de hardware também exigem declarações de comunicação conforme estipulado pelos governos dos países para os quais esses produtos são enviados. Nos EUA, a FCC exige certas declarações de comunicação dependendo da "classe" do produto de hardware. Como escritor, você deve ter cuidado para usar a declaração de comunicação adequada para o produto que está documentando—e não editar a declaração de forma alguma (palavras legais sagradas!).

O índice (TOC) geralmente contém pelo menos um segundo nível de detalhe (os títulos 1 no texto real) para que os leitores possam encontrar o que precisam com mais precisão. Escritores, editores e designers de livros tipicamente discutem sobre a sequência do TOC. Em termos de usabilidade, é muito melhor ter o TOC o mais próximo possível do início do livro, se não na primeira página do livro. Em termos legais, no entanto, as pessoas se preocupam que todas aquelas declarações de comunicação, garantias, direitos autorais, marcas registradas e avisos de segurança deveriam vir primeiro. Nas situações em que a usabilidade prevalece, os livros usam todas as táticas que podem para afastar esse material legalista da parte inicial: garantias são colocadas em cartões separados e embaladas a vácuo com o livro ou produto; garantias, declarações de comunicação, marcas registradas e outros podem ser jogados em apêndices.

Problemas para criar um índice bem formatado? Veja Criar um índice com aparência profissional

Manuais técnicos para usuários comuns normalmente não têm listas de figuras. Na verdade, as figuras em si geralmente não têm títulos de figura completos. Mas isso não quer dizer que uma lista de figuras não tenha lugar em manuais técnicos. Tudo depende do leitor e das necessidades do leitor—e do conteúdo do livro também. Se o livro contém tabelas, ilustrações, gráficos, charts e outros elementos que os leitores desejarão encontrar diretamente, a lista de figuras é necessária.

A função do prefácio é preparar os leitores para ler o livro. Isso é feito por:

• caracterizando o conteúdo e o propósito do livro
• identificando ou até mesmo descrevendo brevemente o produto que o livro apoia
• explicando o tipo de leitor para quem o livro é destinado
• esboçando o conteúdo principal do livro
• mostrando qualquer convenção ou terminologia especial usada no livro
• fornecendo suporte e números de marketing, e outras coisas assim

Na publicação de livros tradicional, o prefácio vem antes do índice; mas, como discutido anteriormente, na índice na seção, as pessoas da publicação técnica querem que o índice venha mais cedo no livro por razões de usabilidade.

Oh sim, e há texto real nesses livros—não é tudo material pré-textual! Pouco mais a dizer aqui além do que a maioria dos livros técnicos tem capítulos ou seções, e, em alguns casos, partes. Veja o capítulo sobre design de página para questões de formato, estilo e design de elementos como cabeçalhos, rodapés, títulos, listas, avisos, tabelas, gráficos, referências cruzadas e destaques.

Como você sabe, apêndices são para materiais que simplesmente não parecem se encaixar na parte principal de um livro, mas que também não podem ser deixados de fora. Apêndices são frequentemente o lugar para grandes tabelas complicadas. Algumas publicações técnicas têm coisas como garantias nos apêndices. Em termos de formato, um apêndice é igual a um capítulo, exceto que é nomeado como "Apêndice A" ou algo do tipo, e os cabeçalhos e rodapés correspondem a essa numeração e convenção de nomenclatura diferentes (A-1, A-2, e assim por diante para as páginas do Apêndice A).

Algumas publicações técnicas incluem uma seção de termos especializados e suas definições. Note que a maioria dos glossários utiliza um layout em duas colunas. Normalmente, cada termo e sua definição compõem um parágrafo separado, com o termo em letras minúsculas (a menos que seja um nome próprio) e em negrito, seguido de um ponto, e então a definição em uma fonte romana regular. Note também que as definições geralmente não são frases completas. Boas definições de glossário devem usar a técnica de definição em frase formal, conforme descrito no capítulo de definição do texto online. Múltiplas definições são geralmente identificadas por números árabes entre parênteses. Os parágrafos do glossário também contêm Ver referências a termos preferidos e Veja também referências a termos relacionados.

Os índices também são tipicamente de duas colunas e também contêm Ver referências a termos preferidos e Veja também referências a termos relacionados. Veja o capítulo sobre indexação para processos e diretrizes para criar bons índices.

Antes do surgimento da Internet e das redes sociais, algumas publicações técnicas continham um formulário impresso para permitir que os leitores enviassem comentários, perguntas e avaliações do livro. É claro que, na verdade, esses formulários mais frequentemente geram reclamações sobre falhas no funcionamento do produto que o livro documenta. Com o advento da Internet, esses formulários foram para o ambiente online, e os livros apenas apontam para sua localização na web.

Design e layout de livro

Tipicamente, os manuais e guias do usuário produzidos por fabricantes de hardware e software são projetados de uma maneira bastante austera e espartana. Empresas de alta tecnologia desenvolvem novas versões e lançamentos de seus produtos às vezes a cada nove meses. Nesse contexto, um design sofisticado simplesmente não é prático. Aqui estão algumas das características típicas de layout e design que você verá:

• O tamanho da página é frequentemente determinado por considerações de embalagens, bem como pelos tamanhos de página padrão disponíveis em empresas de impressão. Quando o tamanho da página não é uma restrição, algumas empresas usam o formato de página de 8,5 × 11 polegadas—isso torna a produção muito mais fácil para os escritores.
• As páginas são tipicamente projetadas com páginas alternadas à direita e à esquerda. O rodapé da página esquerda (par) começa com o número da página e termina com o título do livro. O rodapé da página direita (ímpar) começa com o título do capítulo e termina com o número da página.
• A prática é mista sobre se a numeração das páginas deve ser consecutiva em todo o livro ou por capítulo.
• A menos que as páginas sejam bastante pequenas, o design de cabeçalhos com recuo em relação às páginas é bastante comum em manuais técnicos. O recuo geralmente é de uma a uma polegada e meia.
• As fontes costumam ser Times New Roman tamanho 12 para o texto do corpo e Arial para os cabeçalhos. O espaçamento padrão entre linhas e palavras é utilizado. Veja o capítulo sobre destacando para outros problemas tipográficos.
• As margens são bastante padrão, de uma a duas polegadas em toda a volta. Normalmente, meia polegada a mais é usada nas margens internas para permitir a encadernação.
• Tipicamente, a cor é não usados nestes manuais e guias, geralmente por questões de custo e eficiência.

A mensagem de envio é uma carta de apresentação (ou memorando) ou um e-mail. A carta física (ou memorando) está anexada do lado de fora do manual do usuário com um clipe de papel ou vinculada dentro do manual do usuário. O e-mail contém um link para o manual do usuário ou o manual do usuário em anexo. É uma comunicação de você—o redator do manual do usuário—para o destinatário, a pessoa que solicitou o manual do usuário e que pode até estar lhe pagando pela sua consultoria especializada. Essencialmente, diz "Ok, aqui está o manual do usuário que concordamos que eu completaria até tal data. Resumidamente, contém isso e aquilo, mas não cobre isso ou aquilo. Por favor, revise e me avise se atende suas necessidades."

Índice

Qualquer formato de tabela de conteúdos (TOC) que você usar, estes são os padrões comuns:

• Número da página inicial apenas. Embora alguns geradores automáticos de sumário mostrem a faixa de páginas, o padrão é apenas o número da primeira página.
• Níveis de cabeçalhos a incluir. Conforme mostrado no TOC acima, exiba os dois principais níveis de cabeçalhos, a menos que o guia do usuário tenha muitos subtítulos. O TOC deve fornecer uma maneira rápida de encontrar informações rapidamente.
• Espaçamento e capitalização. Observe como os itens de texto no índice acima estão indentados. Títulos de primeiro nível usam letras maiúsculas; títulos de segundo nível usam letras maiúsculas na primeira letra de cada palavra principal; títulos de terceiro nível usam maiúsculas no estilo de frase.
• Espaçamento vertical. Note que as seções de primeiro nível têm espaço extra acima e abaixo, o que aumenta a legibilidade.

Dependendo das exigências da sua organização, você tem duas opções de formato para tabelas de conteúdo (TOC):

Este índice usa o estilo de numeração decimal para os números dos capítulos e seções, que é comum em manuais do usuário. Outros neste livro usam o estilo de números romanos maiúsculos apenas para os capítulos de nível superior (veja ).

Dificuldade em criar um TOC bem formatado? Veja Crie um índice com aparência profissional

Vírgulas e números de página. Se um formato de líder-ponto não for necessário e você preferir evitá-lo, pode usar este formato comumente aceito:

Veja este exemplo de um prefácio:

Lista de figuras

Não frequentemente incluído nos guias do usuário...

Prefácio

Capítulos Principais do Guia do Usuário

Apêndices

Índice

Outros Elementos do Guia do Usuário

Títulos

Listas com Marcadores e Numeradas

Símbolos, Números e Abreviações

Gráficos e Títulos de Figuras

Referências Cruzadas

Numeração de Páginas

Promptes de IA para Guias de Usuário

Listas de verificação, que tipicamente ficam sem ser lidas, podem ser usadas como fonte para prompts de IA com algumas modificações. Copie o seguinte, cole-o em um sistema de IA como o Gemini do Google e veja o que você pode ter perdido.

Nota: Todas as referências ao conteúdo, formato, estilo dos guias do usuário ou seus componentes podem ser encontradas no livro didático de redação técnica online.

Quando você quiser usar a IA para avaliar um projeto de escrita, apresente-se, diga à IA quem você é e o que você deseja. Dê à IA um ponto de referência para fazer as avaliações, como um livro didático online. Em seguida, publique o que você deseja que a IA verifique em sua avaliação.

Modifique a introdução para se adequar à sua identidade.

Informação Relacionada

Como Escrever Tópicos de Ajuda Amigáveis para Iniciantes. clickhelp.com

Como escrever documentação do usuário. techscribe

Guias do usuário. techscribe

Agradeceria seus pensamentos, reações e críticas em relação a este capítulo: sua resposta—David McMurrey.