Por favor, clique aqui para ajudar David McMurrey pagar pela hospedagem de sites:
Doe qualquer pequeno valor que você puder.
A Escrita Técnica Online continuará gratuita.
Esta página está em manutenção.
A guia do usuário é um documento técnico que explica como realizar tarefas comuns por um usuário de um produto. Comum tarefas são aquelas ações que o usuário precisa ser capaz de realizar. O usuário está em um nível de conhecimento e experiência pretendido pelo produto. Alguns produtos têm usuários básicos e usuários avançados—um guia do usuário pode atender a uma dessas necessidades ou ambas. Pense em um micro-ondas: ele pode ter um usuário básico, e é só isso. Por outro lado, um produto de design gráfico pode ter tanto usuários básicos quanto usuários avançados.
Infográfico gerado pelo NotebookLLM deste capítulo
Neste capítulo, design de livro significa o conteúdo, estilo, formato, design e sequência dos vários componentes típicos de um livro. "Componentes" aqui refere-se a seções ou páginas reais de um livro, como o aviso de edição, o prefácio, o índice ou a capa da frente ou de trás. No capítulo de design de página, o termo elemento refere-se a coisas que podem ocorrer várias vezes praticamente em qualquer lugar de um livro, como cabeçalhos, rodapés, tabelas, ilustrações, listas, avisos, destaques e assim por diante.
A seguir, apresenta-se uma visão geral dos componentes típicos de um livro técnico impresso e do conteúdo, formato, estilo e sequência típicos desses componentes. Certamente, nenhum guia do usuário único, manual de referência técnica, documento de referência rápida ou outro documento desse tipo teria todos esses componentes projetados e sequenciados exatamente da maneira que você vai ler. Em vez disso, esta revisão fornecerá uma visão geral das possibilidades—digamos, a variedade de possibilidades.
Nota: Atualmente, temos apenas um exemplo guia do usuário desenvolvido no FrameMaker e depois exportado para PDF. Falta um glossário, mas todas as outras partes de um guia do usuário típico estão no lugar. (Não consigo entender aquele "d" em "Filepad"!) Esteja ciente de que ele não utiliza alguns dos requisitos de fonte e margens listados abaixo.
Antes de começar a ler o que se segue, pegue vários livros de hardware e software para que você possa comparar seu conteúdo, estilo, formato e sequência com o que é discutido aqui.
Para ainda mais detalhes do que você vê aqui, consulte esses dois recursos padrão da indústria:
- Publicações Técnicas da Sun. Leia-me primeiro! Qualquer edição recente. Prentice Hall.
- Microsoft Corporation. Manual de Estilo da Microsoft para Publicações Técnicas. Qualquer edição recente. Microsoft Press.
Você pode ver exemplos desses componentes de livro em Design de Techdoc.
Capa frontal e capa traseira
Documentos de produtos para clientes pagantes geralmente têm capas frontais bem elaboradas, mesmo que, por dentro, o conteúdo seja de qualidade inferior. Na capa frontal, você normalmente verá alguns ou todos os seguintes:
- Nome da empresa
- Nome do produto
- Plataforma de produto ou sistema operacional
- Números da versão do produto e de lançamento
- Título do livro
- Logos de empresas ou produtos
- Símbolos de marca registrada
- Arte
- Número do pedido do livro
- Slogan da empresa ou do produto
Pode ser desafiador descobrir um bom formato para o nome da empresa, nome do produto e título do livro. Às vezes, isso pode totalizar um parágrafo inteiro de texto! As empresas estão bastante divididas sobre indicar números de versão e lançamento nas capas frontais—algumas fazem; outras não. Quase sempre, no entanto, você verá a plataforma indicada—se o produto é para Macintosh, PC, UNIX e assim por diante.
Exemplo de uma capa.
A contracapa de guias e manuais de usuário em formato impresso geralmente é muito simples. Normalmente, contém o número do pedido do livro, o nome da empresa com os símbolos de marca registrados apropriados, um símbolo de copyright e uma frase sobre a propriedade do livro, além de uma declaração sobre em qual país o livro foi impresso. Você também encontrará códigos de barras na contracapa. Veja se seu software pode gerar um código de barras—você só precisa acessar a utilidade de código de barras e digitar o número do pedido do livro, e a utilidade gera o código de barras.
Página de título
A página de título é tipicamente uma duplicata da capa frontal, mas com certos elementos omitidos. Geralmente omitidos estão a arte, logotipos de empresas ou produtos e slogans. Algumas publicações técnicas omitem a página de título completamente devido à duplicação aparentemente desnecessária. (E em uma tiragem de 20.000 cópias, uma única página conta muito!)
Exemplo de uma página de título.
aviso de edição
O aviso de edição é tipicamente a primeira instância de texto regular em uma publicação técnica, embora geralmente esteja em um tipo menor. Ele ocorre no verso da página de título. Se o editor técnico está adotando a abordagem enxuta e verde e eliminando a página de título, o aviso de edição aparecerá no verso da capa frontal.
Ninguém gosta de ler letras pequenas, mas dê uma olhada nas declarações geralmente incluídas em um aviso de edição:
Exemplo de um aviso de edição
Marcas Registradas
A forma como você lista as marcas registradas e a forma como você ouve é competência dos advogados da empresa. De qualquer forma, você lista apenas os nomes de produtos registrados como marcas que aparecem naquele guia do usuário específico.
Mais comumente, as marcas registradas são indicadas:
- na nota de edição (como a ilustração acima mostra)
- em uma seção separada em algum lugar no guia do usuário
mencione aquela nota
Se os advogados corporativos quiserem que cada ocorrência de um nome de produto registrado seja indicada com um asterisco ou nota de rodapé, tente dissuadi-los desse fiasco de design de página. Poluir o texto com asteriscos ou números de nota de rodapé distrai os leitores.
Garantias
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 exemplo de guia do usuário ou livro para seu portfólio, pode usar este "exemplo de garantia" anônimo.janela pop-up para mostrar que você está ciente de que as garantias devem ser incluídas.
garantias de software?Avisos de segurança
Os produtos de hardware geralmente têm uma seção de avisos de segurança no início de seus livros. 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 normalmente 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 inicial, os livros de hardware ainda colocam os avisos individuais nos pontos onde se aplicam. (Para mais informações, veja avisos especiais.)
Declarações de comunicação
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 correta para o produto que você está documentando—e não editar a declaração de forma alguma (palavras legais sagradas!).
Índice
O índice (TOC) geralmente contém pelo menos um segundo nível de detalhe (os cabeçalhos 1 no texto real) para que os leitores possam encontrar o que precisam com mais precisão. Escritores, editores e designers de livros costumam discutir 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. No entanto, em termos de legalidades, as pessoas se preocupam que todas aquelas declarações de comunicação, garantias, direitos autorais, marcas registradas e avisos de segurança devam vir primeiro. Nos locais onde a usabilidade prevalece, os livros usam todas as táticas possíveis para retirar esse material legal da parte inicial: as 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 documentos semelhantes podem ser incluídos em apêndices.
Problemas para criar um índice formatado corretamente? Veja Crie um índice com aparência profissional
Lista de figuras
Manuais técnicos para usuários comuns tipicamente não têm listas de figuras. Na verdade, as figuras em si não costumam ter títulos completos. Mas isso não significa 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 contiver tabelas, ilustrações, gráficos, tabelas e outros elementos que os leitores desejarão encontrar diretamente, a lista de figuras é necessária.
Prefácio
A função do prefácio é preparar os leitores para ler o livro. Ela faz isso ao:
- 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 os principais conteúdos do livro
- mostrando quaisquer convenções ou terminologia especial usadas 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 no í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.
Capítulos do corpo
Oh sim, e há texto real nesses livros—não é tudo material de abertura! Pouco mais a dizer aqui além de 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.
Apêndices
Como você sabe, apêndices são para material que simplesmente não parece se encaixar na parte principal de um livro, mas que também não pode ser deixado de fora. Os apêndices são frequentemente o lugar para grandes tabelas difíceis de manejar. Algumas publicações técnicas têm coisas como garantias nos apêndices. Em termos de formato, um apêndice é exatamente como um capítulo, exceto que é nomeado "Apêndice A" ou algo do tipo, e os cabeçalhos e rodapés correspondem a essa numeração e convenção de nomes diferentes (A-1, A-2, e assim por diante para as páginas do Apêndice A).
Glossário
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 de duas colunas. Normalmente, cada termo e sua definição constituem 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, então a definição em romanos regulares. 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 deste texto online. Múltiplas definições são normalmente identificadas por números árabes entre parênteses. Os parágrafos do glossário também contêm Ver referências aos termos preferidos e Veja também referências a termos relacionados.
Índice
Os índices também são tipicamente de duas colunas e também contêm Veja 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.
Formulário de resposta do leitor
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 frequentemente geravam reclamações sobre falhas de funcionamento no produto que o livro documenta. Com o surgimento da Internet, esses formulários foram para o online, e os livros apenas apontam para sua localização na internet.
Design e layout de livros
Normalmente, os guias do usuário e manuais produzidos por fabricantes de hardware e software são projetados de 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 embalagem, bem como pelos tamanhos de página padrão disponíveis nas empresas de impressão. Quando o tamanho da página não é uma restrição, algumas empresas usam o tamanho 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 direita e esquerda alternadas. 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 em relação às páginas, com recuo, é bastante comum em manuais técnicos. O recuo geralmente varia de uma polegada a uma polegada e meia.
- As fontes são frequentemente Times New Roman tamanho 12 para o texto do corpo e Arial para os títulos. Espaçamento de linha e espaçamento de palavras padrão são usados. Consulte o capítulo sobre destacando para outros problemas tipográficos.
- As margens são bastante padrão, de uma a duas polegadas em volta. Normalmente, uma meia polegada extra é usada nas margens internas para permitir a encadernação.
- Tipicamente, a cor é não usado nestes manuais e guias, geralmente por questões de custo e eficiência.
Índice
Í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 somente. 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 primeiros 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 indented. Títulos de primeiro nível usam letras maiúsculas; títulos de segundo nível usam letras maiúsculas apenas na primeira letra de cada palavra principal; títulos de terceiro nível usam estilo de frase com letras iniciais em maiúsculas.
- Espaçamento vertical. Note que as seções de primeiro nível possuem espaço extra acima e abaixo, o que aumenta a legibilidade.
Dependendo das necessidades da sua organização, você tem duas opções de formato para tabelas de conteúdos (TOC):
Este TOC usa o estilo de numeração decimal para os números de capítulo e seção, o que é comum em manuais do usuário. Outros neste livro usam o estilo de numeração romana maiúscula apenas para os capítulos de nível superior (veja).
Dificuldade em criar um índice bem formatado? Veja Crie um TOC 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:
Texto simples de índice com vírgulas e número da página.Lista de figuras
Não é frequentemente incluído nos manuais do usuário...
-->Prefácio
Capítulos Principais do Guia do Usuário
Apêndices
Índice
Outros Elementos do Guia do Usuário
Cabeçalhos
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 do Usuário
Listas de verificação, que geralmente ficam sem leitura, podem ser usadas como fonte para prompts de IA com algumas modificações. Copie o seguinte, cole 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 em livro-texto de redação técnica online.
Quando você quer usar IA para avaliar um projeto de escrita, comece se apresentando, diga à IA quem você é e o que você deseja. Dê à IA um ponto de referência para realizar as avaliações, como um livro didático online. Em seguida, poste o que você quer que a IA verifique em sua avaliação.
Modifique a introdução para se adequar à sua identidade.
|
Guias do Usuário de Prompts de IA Olá, IA. Estou solicitando que você avalie as instruções escritas por um estudante do segundo ano da faculdade dos EUA. Abaixo está um resumo dos capítulos do livro didático sobre instruções e avisos para usar como base da sua avaliação. (Informações de identificação mascaradas):
|
Informações Relacionadas
Como Escrever Tópicos de Ajuda Amigáveis para Iniciantes. clickhelp.com
Como escrever documentação para o usuário. techscribe
Guias do usuário. techscribe
Eu apreciaria seus pensamentos, reações e críticas sobre este capítulo: sua resposta—David McMurrey.
