Por favor, clique aqui para ajudar David McMurrey pagar pelo hospedagem de sites:
Doe qualquer quantia pequena que você puder
A escrita técnica online continuará sendo gratuita.
Esta página está em manutenção.
A guia do usuário é um documento técnico explicando 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 é 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 refere-se ao 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 da edição, o prefácio, o índice ou a capa frontal ou traseira. No a 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, é apresentado um resumo 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, manual de referência técnica, documento de consulta rápida ou outro documento desse tipo teria, na verdade, todos esses componentes projetados e sequenciados exatamente da maneira que você está prestes a ler. Em vez disso, esta revisão fornecerá uma visão geral das possibilidades—digamos, a faixa 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 presentes. (Não consigo entender aquele "d" em "Filepad"!) Esteja ciente de que não utiliza alguns dos requisitos de fonte e margem listados abaixo.
Antes de começar a ler o seguinte, pegue alguns livros de hardware e software para que você possa comparar seu conteúdo, estilo, formato e sequenciamento com o que é discutido aqui.
Para ainda mais detalhes do que você vê aqui, consulte esses dois recursos padrão da indústria:
- Documentos Técnicos da Sun. Leia-me Primeiro! Qualquer edição recente. Prentice Hall.
- Microsoft Corporation. Manual da Microsoft de Estilo para Publicações Técnicas. Qualquer edição recente. Microsoft Press.
Você pode ver exemplos desses componentes do livro em Design de Techdoc.
Capa frontal e capa traseira
Documentos de produto para clientes pagantes geralmente têm capas frontais bem projetadas, mesmo que, por dentro, o livro seja de qualidade inferior. Na capa da frente, você verá normalmente alguns ou todos os seguintes:
- Nome da empresa
- Nome do produto
- Plataforma de produto ou sistema operacional
- Versão do produto e números 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 produto
Pode ser desafiador encontrar um bom formato para o nome da empresa, nome do produto e título do livro. Às vezes, isso pode somar a 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 o 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 dos guias e manuais impressos geralmente é muito simples. Normalmente, contém o número do pedido do livro, o nome da empresa com os símbolos de registro apropriados, um símbolo de copyright e uma redação sobre a propriedade do livro, além de uma declaração sobre 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—basta acessar a ferramenta de código de barras e digitar o número do pedido do livro, e a ferramenta gera o código de barras.
Página de título
A página de título é geralmente uma duplicata da capa frontal, mas com certos elementos omitidos. Normalmente, são omitidos a arte, logotipos da empresa ou do produto e slogans. Algumas publicações técnicas omitem a página de título completamente devido à duplicação que parece desnecessária. (E em uma tiragem de 20.000 cópias, uma única página significa 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 normalmente esteja em um tipo menor. Ele aparece no verso da página de título. Se o editor técnico estiver adotando uma abordagem enxuta e sustentável 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 miúdas, mas dê uma olhada nas declarações normalmente incluídas em um aviso de edição:
Exemplo de um aviso de edição
Marcas Registradas
Se você lista marcas registradas e como você as escuta é assunto dos advogados da empresa. Em qualquer caso, você lista apenas aqueles nomes de produtos registrados que ocorrem naquele guia do usuário específico.
Mais comumente, as marcas 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 querem que cada ocorrência de um nome de produto registrado seja indicada com um asterisco ou nota de rodapé, tente convencê-los a desistir daquela armadilha de design de página. Poluir o texto com asteriscos ou números de notas de rodapé é distrativo para 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 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.
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 geralmente reúnem todos os avisos de perigo, aviso 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 em que se aplicam. (Para mais informações, see avisos especiais.)
Declarações de comunicação
Os 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 está documentando—e não editar a declaração de maneira alguma (palavras legais sagradas!).
Tabela de conteúdos
O índice geralmente contém pelo menos um segundo nível de detalhes (os cabeçalhos 1 no texto real) para que os leitores possam encontrar o que precisam de forma mais precisa. Escritores, editores e designers de livros costumam discutir sobre a sequência do índice. Em termos de usabilidade, é muito melhor ter o índice o mais próximo possível do começo do livro, se não na primeira página. Em termos legais, no entanto, as pessoas se preocupam que todas essas declarações de comunicação, garantias, direitos autorais, marcas registradas e avisos de segurança deveriam vir primeiro. Nos lugares onde a usabilidade prevalece, os livros usam todas as táticas que podem para retirar esse material legal 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 que tais podem ser colocados em apêndices.
Problemas para criar um TOC bem formatado? Veja Crie um índice com aparência profissional
Lista de figuras
Manuais técnicos para usuários comuns geralmente não têm listas de figuras. Na verdade, as figuras em si normalmente não têm títulos completos. Mas isso não quer dizer que uma lista de figuras não tenha seu 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, tabelas de dados e outros itens que os leitores desejam 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 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 os principais conteúdos do livro
- mostrando quaisquer convenções ou terminologia especiais usadas no livro
- fornecendo suporte e números de marketing, e outras coisas do tipo
Na publicação de livros tradicional, o prefácio vem antes do índice; mas como discutido anteriormente no índice na seção, as pessoas de 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 prévio! Pouco mais a dizer aqui, além do fato 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 destaque.
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. 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 é igual a um capítulo, exceto que é chamado de "Apêndice A" ou algo similar, e os cabeçalhos e rodapés seguem essa nomenclatura e numeração 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 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 por um ponto, e então a definição em romano regular. Observe também que as definições geralmente não são sentenças completas. Boas definições de glossário devem usar a técnica de definição de sentença formal conforme descrito no capítulo de definição deste texto online. Múltiplas definições geralmente são 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.
Índice
Os índices geralmente são compostos por 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.
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 costumavam gerar reclamações sobre falhas no funcionamento do produto que o livro documenta. Com o crescimento da Internet, esses formulários foram para o online, e os livros apenas indicam sua localização na web.
Design e layout de livros
Normalmente, os guias e manuais do usuário produzidos por fabricantes de hardware e software são projetados de forma 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 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 utilizarão 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 geralmente 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 ao longo do livro ou por capítulo.
- A menos que as páginas sejam bastante pequenas, o design de cabeçalhos suspensos em relação às páginas é bastante comum em manuais técnicos. O recuo suspenso é geralmente de uma polegada a uma polegada e meia.
- As fontes costumam ser tamanho 12 em Times New Roman para o corpo do texto e Arial para os títulos. O espaçamento entre linhas e as palavras são padronizados. Veja o capítulo sobre destacando para outros problemas tipográficos.
- As margens são bastante padrão, de uma a duas polegadas ao redor. Normalmente, uma meia polegada extra é usada nas margens internas para permitir a encadernação.
- Normalmente, a cor é não usado nestes manuais e guias, geralmente por questões de custo e eficiência.
A mensagem de envio é um ofício (ou memorando) ou um e-mail. A carta física (ou memorando) está anexada do lado de fora do guia do usuário com um clipe de papel ou encadernada dentro do guia do usuário. O e-mail contém um link para o guia do usuário ou o guia do usuário anexado. É uma comunicação de você—o autor do guia do usuário—para o destinatário, a pessoa que solicitou o guia do usuário e que pode até estar pagando por sua consultoria especializada. Essencialmente, diz "Ok, aqui está o guia do usuário que concordamos que eu teria concluído até tal data. Resumidamente, contém isso e aquilo, mas não cobre isso ou aquilo. Por favor, revise e me avise se atende às suas necessidades."
Índice
Índice
Independentemente do formato da tabela de conteúdos (TOC) que você utilizar, 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 índice acima, exiba os dois principais níveis de cabeçalhos, a menos que o guia do usuário tenha muitos subtópicos. O índice deve proporcionar uma maneira rápida de encontrar informações de forma ágil.
- Espaçamento e capitalização. Observe como os itens de texto no TOC acima estão indentados. Os títulos de primeiro nível usam todas as letras maiúsculas; os títulos de segundo nível usam maiúsculas na letra inicial de cada palavra principal; os títulos de terceiro nível usam maiúsculas em estilo de sentença.
- Espaçamento vertical. Observe que as seções de primeiro nível têm espaço extra acima e abaixo, o que aumenta a legibilidade.
Dependendo dos requisitos da sua organização, você tem duas opções de formato para tabelas de conteúdo (TOC):
Este índice usa estilo de numeração decimal para os números de capítulos e seções, o que é comum em guias do usuário. Outros neste livro usam o estilo de numeração romana maiúscula apenas para os capítulos de alto nível (veja).
Problemas para 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 ponto de líder não for necessário e você preferir evitá-lo, pode usar este formato geralmente aceito:
Veja este exemplo de um prefácio:
Texto simples de índice com vírgulas e número de 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
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
Prompts de IA para Guias do Usuário
Listas de verificação, que normalmente ficam sem leitura, 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 Google Gemini 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 o livro didático de escrita 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ê quer. Dê à IA um ponto de referência para fazer as avaliações, como um livro didático online. Então, 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 para Prompts de IA Olá, IA. Estou solicitando que você avalie instruções escritas por um aluno do segundo ano de faculdade dos EUA. Abaixo está um resumo dos capítulos do livro texto sobre instruções e avisos para usar como base de sua avaliação. (Informações identificáveis ocultadas):
|
Informações Relacionadas
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
Eu apreciaria seus pensamentos, reações e críticas sobre este capítulo: sua resposta—David McMurrey.
