Por favor, clique aqui para ajudar David McMurrey pagar pela hospedagem de sites:
Doe qualquer quantia que puder!
A Escrita Técnica Online continuará gratuita.
Documentos técnicos (incluindo manuais, artigos e guias) possuem diversos designs dependendo da indústria, profissão ou organização. Este capítulo mostra um design tradicional. Se você está fazendo um curso de redação técnica, certifique-se de que o design apresentado neste capítulo é aceitável. O mesmo se aplica se você estiver escrevendo um documento técnico em um contexto de ciência, negócios ou governo.
Infográfico gerado pelo NotebookLM deste capítulo
Nota: Por anos, este livro didático de escrita técnica online se referiu genericamente a relatórios como praticamente qualquer coisa que contenha informações técnicas. Mas como "relatório" se refere a um gênero específico de documento técnico, a mudança teve que ser feita para o genérico "techdoc," abreviação de documento técnico.
Techdocs (nome genérico para documentos técnicos) têm especificações assim como qualquer outro tipo de projeto. As especificações para techdocs envolvem layout, organização e conteúdo, formato de títulos e listas, o design dos gráficos, e assim por diante. A vantagem de uma estrutura e formato exigidos para techdocs é que você ou qualquer outra pessoa pode esperar que eles sejam projetados de uma maneira familiar—você sabe o que procurar e onde procurar. Techdocs geralmente são lidos às pressas—as pessoas estão apressadas para acessar as informações de que precisam, os fatos principais, as conclusões e outros itens essenciais. Um formato padrão de techdoc é como um bairro familiar.
Ao analisar o design de um techdoc, perceba como algumas seções são repetitivas. Essa duplicação está relacionada à forma como as pessoas leem techdocs. Elas não leem os techdocs de forma linear: podem começar com o resumo executivo, pular partes e provavelmente não lerão todas as páginas. Seu desafio é projetar techdocs para que esses leitores encontrem seus fatos e conclusões principais, independentemente de quanto do techdoc eles leiam ou em que ordem o leem.
Certifique-se de ver o exemplo de techdocs.
Os componentes padrão do relatório técnico típico são discutidos neste capítulo. As seções a seguir o guiarão por cada um desses componentes, apontando as características principais. Ao ler e utilizar estas diretrizes, lembre-se de que são diretrizes, não mandamentos. Diferentes empresas, profissões e organizações têm suas próprias diretrizes variadas para documentos técnicos — você precisará adaptar sua prática àquelas, bem como às apresentadas aqui.
Mensagem de Transmissão
A mensagem de transmittal é uma carta de apresentação (ou memorando) ou um e-mail. A carta física (ou memorando) está anexada na parte externa do documento técnico com um clipe de papel ou vinculada dentro do documento técnico. O e-mail contém um link para o documento técnico ou o documento técnico anexado. É uma comunicação de você—o autor do documento técnico—para o destinatário, a pessoa que solicitou o documento técnico e que pode até estar pagando você pela sua consultoria especializada. Essencialmente, diz "Ok, aqui está o documento técnico que concordamos que eu completaria até tal data. Resumidamente, contém isso e aquilo, mas não cobre isso ou aquilo. Me avise se atende suas necessidades." A mensagem de transmittal explica o contexto—os eventos que levaram à criação do documento técnico. Contém informações sobre o documento técnico que não pertencem ao documento técnico.
Exemplos de uma carta de transmittal e mensagem de transmittal.
No exemplo da carta de transmittal, observe o formato padrão de carta comercial. Se você escrever um techdoc interno, use o formato de memorando; em ambos os casos, o conteúdo e a organização são os mesmos:
Primeiro parágrafo. Cita o nome do techdoc, colocando-o em itálico. Também menciona a data do acordo para escrever o techdoc.
Parágrafo do meio. Concentra-se no propósito do techdoc e fornece uma breve visão geral do conteúdo do techdoc.
Parágrafo final. Incentiva o leitor a entrar em contato se houver perguntas, comentários ou preocupações. Fecha com um gesto de boa vontade, expressando a esperança de que o leitor ache o documento técnico satisfatório.
Assim como qualquer outro elemento em um documento técnico, você pode precisar modificar o conteúdo desta mensagem (ou memorando) para situações específicas. Por exemplo, você pode querer adicionar outro parágrafo, listando perguntas que você gostaria que os leitores considerassem ao revisar o documento técnico.
Capas, Página de Título e Rótulo
Se seu documento técnico tiver mais de dez páginas, encaderne-o de alguma forma e crie um rótulo para a capa.
Capa
As capas dão aos techdocs uma aparência sólida e profissional, além de proteção. Você pode escolher entre muitos tipos de capas. Mantenha estas dicas em mente:
- Totalmente inaceitáveis são as capas plásticas transparentes (ou coloridas) com a manga de plástico na borda esquerda. Elas parecem algo saído de uma aula de inglês do primeiro ano; além disso, são irritantes de usar—os leitores devem se esforçar para mantê-las abertas e lidar com a eletricidade estática que geram.
- Marginalmente aceitáveis são as capas nas quais você faz furos nas páginas, carrega as páginas e dobra os grampos. Se você usar esse tipo, deixe uma margem extra de meia polegada na borda esquerda para que os leitores não precisem forçar as páginas. Claro, esse tipo de capa impede que as páginas fiquem planas: os leitores devem agarrar objetos disponíveis ou usar várias partes do corpo para manter as páginas pesadas.
- De longe, as melhores capas são aquelas que permitem que os documentos técnicos fiquem abertos sozinhos (veja a ilustração na próxima seção). Que grande alívio para um documento técnico ficar aberto em seu colo ou na sua mesa. Este tipo usa uma espiral plástica para a encadernação e papel cartão grosso para as capas. Consulte sua gráfica local sobre esses tipos de encadernações; elas são baratas e acrescentam profissionalismo ao seu trabalho. Veja o exemplo simulado de uma encadernação com espiral plástica a seguir.
Geralmente, são menos preferíveis os cadernos de folhas soltas ou pastas com argolas. Esses são muito volumosos para documentos técnicos curtos, e os furos das páginas tendem a rasgar. Claro, a pasta com argolas facilita a troca de páginas; se é assim que seu documento técnico será usado, então é uma boa escolha. No "alto nível", estão as capas excessivamente sofisticadas com aparência de couro sintético e detalhes em dourado. Evite-as—mantenha simples, direto e funcional.
Página de Título
Em sua forma mais simples, um título de techdoc é uma cópia do que está na capa—possivelmente com alguns detalhes adicionados.
Dê uma olhada na página de título Resumo e Sumário Executivo.
Rótulos
Certifique-se de criar um rótulo para a capa do seu documento técnico. É um passo que alguns escritores de documentos técnicos esquecem. Sem um rótulo, um documento técnico é anônimo; ele é ignorado.
A melhor maneira de criar um rótulo é usar seu software de processamento de texto para projetar um em uma página padrão com uma caixa gráfica ao redor das informações do rótulo. Imprima, depois vá a uma copiadora e faça uma cópia diretamente na capa do documento técnico.
Não há muito o que colocar no rótulo: o título do documento técnico, seu nome, o nome da sua organização, um número de rastreamento do documento técnico e uma data. Não existem requisitos padrão para o rótulo, embora sua empresa ou organização deva ter seus próprios requisitos. (Um exemplo de rótulo de documento técnico é mostrado abaixo.)
Carta de envio e capa do documento técnico (com etiqueta de capa).
Resumo e Sumário Executivo
A maioria dos documentos técnicos contém pelo menos um resumo__ENTIDADE_0__às vezes dois, quando os resumos desempenham papéis diferentes. Os resumos resumem o conteúdo de um documento técnico, mas os diferentes tipos fazem isso de maneiras diferentes:
- Resumo descritivo. Este tipo fornece uma visão geral do propósito e dos conteúdos do techdoc. Em alguns designs de techdoc, o resumo descritivo é colocado na parte inferior da página de título, conforme mostrado a seguir:
Resumo descritivo. Traditionamente, é colocado na página de título (não na capa). - Resumo executivo. Outro tipo comum é o resumo executivo, que também resume os fatos e conclusões principais contidos no documento técnico. Veja o exemplo mostrado a seguir. É como se você usasse um marcador amarelo para marcar as frases-chave no documento técnico e, em seguida, as transferisse todas para uma página separada e as editasse para facilitar a leitura. Normalmente, os resumos executivos têm uma extensão de um décimo a um vigésimo do comprimento de documentos técnicos de dez a cinquenta páginas. Para documentos técnicos mais longos, aqueles com mais de cinquenta páginas, o resumo executivo não deve ultrapassar duas páginas. O objetivo do resumo executivo é fornecer um resumo do documento técnico algo que possa ser lido rapidamente.
Se o resumo executivo, a introdução e a mensagem de transmittal parecem repetitivos, lembre-se de que os leitores não necessariamente começam no início de um documento técnico e leem página por página até o final. Eles pulam partes: podem escanear o índice; geralmente folheiam o resumo executivo em busca de fatos e conclusões importantes. Eles podem ler atentamente apenas uma seção ou duas do corpo do documento técnico e, em seguida, pular o restante. Por essas razões, os documentos técnicos são projetados com alguma duplicação para que os leitores tenham certeza de ver as informações importantes, não importa onde eles comecem a ler o documento.
Índice (o que vem primeiro) depois o resumo executivo.
Í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 TOC 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 documento técnico tenha muitos subtítulos. O TOC deve fornecer uma maneira rápida de encontrar informações de forma rápida.
- 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 letras maiúsculas; os títulos de segundo nível usam maiúsculas iniciais em cada palavra principal; os títulos de terceiro nível usam letras maiúsculas no estilo de frase.
- 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.
- Todas as páginas do techdoc (dentro, mas excluindo as capas da frente e de trás) estão numeradas; mas em algumas páginas, os números não são exibidos.
- No design contemporâneo, todas as páginas do documento usam números arábicos; no design tradicional, todas as páginas antes da introdução (primeira página do corpo do ) usam números romanos em minúsculas.
- Em páginas especiais, como a página de título e a página um da introdução, os números das páginas não são exibidos.
- Os números das páginas podem ser colocados em uma das várias áreas da página. Normalmente, a melhor e mais fácil escolha é colocar os números das páginas no centro inferior da página (lembre-se de escondê-los em páginas especiais).
- Se você colocar os números das páginas no topo da página, deve escondê-los em aberturas de capítulos ou seções onde um cabeçalho ou título está no topo da página.
- O techdoc (relatório) contém o seguinte (formatado corretamente) nesta ordem: mensagem de transmissão; página de título; tabela de conteúdos; lista de figuras, tabelas ou ambos; introdução; seções do corpo (capítulos); apêndices (se necessário); fontes de informação; contracapa (se necessário). Para mais detalhes, veja Design de Techdoc.
- Embora possa ser engenhoso e brincalhão, o título do documento técnico indica adequadamente seu assunto? Para mais detalhes, veja Títulos de Techdoc.
- Se o índice e a lista de figuras (e tabelas) utilizam pontos de líderes, os números de página estão alinhados à direita. Se o índice e a lista de figuras (e tabelas) incluem números de página na borda direita da página, os pontos de líderes são utilizados? Para detalhes, veja Sumários e Lista de Figuras (Tabelas).
- A introdução indica adequadamente o tópico, propósito e público-alvo do techdoc? Ela fornece uma lista de subtópicos a serem abordados e uma indicação do escopo (o que não está coberto)? Para mais detalhes, veja Introduções.
- Este documento técnico contém detalhes adequados, especificidades, exemplos—o que for necessário para explicar as afirmações, as generalidades?
- Considerando o tema, o propósito e o público, há algum conteúdo vital faltando neste documento técnico? Há algum conteúdo desnecessário? Alguma informação neste documento técnico está tecnicamente incorreta? Está faltando alguma informação técnica crítica?
- Neste documento técnico, há alguma informação claramente emprestada que não está documentada de nenhuma forma?
- As citações (referências a itens na lista de fontes de informação) ocorrem no corpo do documento técnico formatado de acordo com o estilo APA, MLA ou IEEE modificado? Os itens na lista de fontes de informação estão formatados de acordo com o estilo APA, MLA ou IEEE modificado? Para mais detalhes, veja Documentação: fontes de informação emprestadas.
- Todas as tabelas e figuras não decorativas incluem um título descritivo (legenda) e fonte (se necessário)? Para mais detalhes, veja Títulos da tabela.
- Todas as tabelas e figuras não decorativas aparecem o mais perto possível de seu texto relevante?
- As referências cruzadas explicativas ocorrem brevemente antes das tabelas e figuras não decorativas? Para detalhes, veja Referências cruzadas explicativas.
- É utilizado um formato padrão de títulos e subtítulos no corpo do techdoc? Para mais detalhes, consulte Títulos.
- As seções principais (capítulos) do documento técnico começam em uma nova página nas versões impressas?
- As listas verticais numeradas são usadas para itens de lista em uma ordem requerida? As listas verticais com marcadores são usadas para itens de lista sem ordem requerida? Os introdutores são usados antes de todas as listas? Para detalhes, veja Listas verticais.
- As citações diretas estão atribuídas e as atribuições estão pontuadas corretamente? Todas as citações diretas, resumos e paráfrases estão devidamente citados de acordo com o estilo APA, MLA ou IEEE modificado? Para detalhes, veja Citações e atribuições.
- O texto do techdoc está livre de erros de gramática, uso e pontuação? Para mais detalhes, veja Problemas Comuns de Gramática, Uso e Ortografia.
- O texto do documento técnico está livre de prolixidade e outros erros de estilo de frase? Para mais detalhes, consulte Verborragia, outros problemas de estilo de frase.
- Este documento técnico pode ser compreendido pelo seu público-alvo (conforme indicado na mensagem de transmissão e na introdução)? Para detalhes, veja Análise de público, e veja Traduzindo o Técnico.
- IA, para completar sua avaliação do meu techdoc, atribua uma nota numérica de 100 a 55).
Pontos de liderança e números de página alinhados à direita. Para o índice tradicional que utiliza pontos de liderança e números de página alinhados à direita:
Alinhamento à direita. Neste exemplo, observe que os pontos de líder "seguem" os números de página que estão alinhados à direita.
Pontos de líder e números de página alinhados à direita.
Este TOC utiliza o estilo de numeração decimal para os números de capítulo e seção, que é comum em documentos técnicos. Outros neste livro usam o estilo de numeração romana maiúscula apenas para os capítulos de nível superior (veja).
Problemas ao criar um índice bem formatado? Veja Criar 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:
|
3. PRINCÍPIOS CHAVE DA EFICIÊNCIA ENERGÉTICA, 5
Estratégias de Design Passivo, 6
4. NORMAS E CERTIFICAÇÕES, 11Sistemas de Energia Ativa, 7 Integração de Energia Renovável, 9
LEED, 11
Energy Star, 12 Desafio da Edificação Viva, 14 |
Lista de Figuras e Tabelas
A lista de figuras possui muitas das mesmas considerações de design que a tabela de conteúdos. Os leitores usam a lista de figuras para encontrar as ilustrações, diagramas, tabelas e gráficos em seu documento técnico.
Complicações surgem quando você tem tanto tabelas quanto figuras. Falando estritamente, figuras são ilustrações, desenhos, fotografias, gráficos e quadros. Tabelas são linhas e colunas de palavras e números; elas não são consideradas figuras.
Para documentos técnicos mais longos que contêm dezenas de figuras e tabelas, crie listas separadas de figuras e tabelas. Junte-as na mesma página se couber, conforme mostrado na ilustração abaixo. Você pode combinar as duas listas sob o título "Lista de Figuras e Tabelas" e identificar os itens como figura ou tabela, como feito na ilustração abaixo.
Introdução
Um elemento essencial de qualquer documentação técnica é sua introdução—certifique-se de estar claro sobre seu verdadeiro propósito e conteúdo. Em uma documentação técnica, a introdução prepara o leitor para ler o corpo principal da documentação técnica. Veja apresentações para uma discussão sobre a escrita de introduções.
Veja este exemplo de uma introdução:
Lista de figuras e tabelas seguida pela introdução.
Se não houver tabelas, faça "Lista de Figuras." Em um curso de redação técnica, pergunte ao seu instrutor se o estilo de numeração decimal para os títulos é necessário.
Corpo do Techdoc
O corpo do techdoc é, claro, o texto principal do techdoc, as seções entre a introdução e a conclusão. Ilustradas abaixo estão páginas de exemplo.
Títulos
Em todas as techdocs, exceto nas mais curtas (duas páginas ou menos), use cabeçalhos para demarcar os diferentes tópicos e subtópicos abordados. Os cabeçalhos permitem que os leitores passem os olhos pela sua techdoc e se aprofundem nos pontos onde você apresenta informações que desejam. Veja títulos para diretrizes sobre cabeçalhos.
Listas com marcadores e numeradas
No corpo de um techdoc, utilize também listas com marcadores, numeradas e em duas colunas quando apropriado. As listas ajudam a enfatizar pontos-chave, a tornar a informação mais fácil de seguir e a quebrar blocos sólidos de texto. Veja listas para diretrizes sobre listas.
Símbolos, Números e Abreviações
Discussões técnicas normalmente contêm muitos símbolos, números e abreviações. Lembre-se de que as regras para usar números em vez de palavras são diferentes no mundo técnico. A antiga regra de escrever todos os números abaixo de 10 não se aplica sempre em documentos técnicos. (Veja números vs palavras para diretrizes.)
Exceto do corpo de um techdoc.
Em um curso de redação técnica, pergunte ao seu instrutor se o estilo de numeração decimal para os títulos é obrigatório. Além disso, pode ser necessário um sistema de documentação diferente—não o IEEE, que é para engenheiros.
Gráficos e Títulos de Figuras
Em documentos técnicos, é provável que você precise de desenhos, diagramas, tabelas e gráficos. Estes não apenas transmitem certos tipos de informação de forma mais eficiente, mas também conferem ao seu documento técnico uma aparência adicional de profissionalismo e autoridade. Se você nunca adicionou esse tipo de gráfico a um documento, existem algumas maneiras relativamente fáceis de fazê-lo—você não precisa ser um artista gráfico profissional. Para estratégias de adição de gráficos, veja gráficos. Para estratégias de adição de tabelas a s, veja mesas.
Referências cruzadas
Você pode precisar direcionar os leitores a informações estreitamente relacionadas dentro de seus techdos, ou a outras fontes de informação que tenham dados relevantes. Esses são chamados de referências cruzadas. Por exemplo, eles podem direcionar os leitores da discussão de um mecanismo para uma ilustração dele. Eles podem direcionar os leitores para um apêndice onde são fornecidas informações de fundo sobre um tópico (informações que simplesmente não se encaixam no texto). E eles podem direcionar os leitores para fora do seu documento técnico para outras informações—para artigos, documentos técnicos e livros que contêm informações relacionadas às suas. Ao criar referências cruzadas, siga estas diretrizes apresentadas em referências cruzadas.
Conclusões
Para a maioria dos techdocs, você precisará incluir uma seção final. Quando você planeja a seção final do seu techdoc, pense sobre as funções que ela pode desempenhar em relação ao resto do techdoc. Ideias para seções finais são apresentadas em conclusões.
Apêndices
Os apêndices são seções extras que seguem a conclusão. O que você coloca nos apêndices? — Qualquer coisa que não se encaixe confortavelmente na parte principal do documento técnico, mas que não possa ser deixada de fora do documento técnico como um todo. O apêndice é comumente usado para grandes tabelas de dados, grandes trechos de código de exemplo, mapas desdobráveis, informações de fundo que são muito básicas ou muito avançadas para o corpo do documento técnico, ou grandes ilustrações que simplesmente não se encaixam no corpo do . Qualquer coisa que você sinta ser muito grande para a parte principal do documento técnico ou que você acha que seria distrativa e interromperia o fluxo do documento técnico é uma boa candidata para um apêndice. Observe que cada um é atribuído uma letra (A, B, C e assim por diante).
Fontes de Informação
Documentar suas fontes de informação é tudo sobre estabelecer, manter e proteger sua credibilidade na profissão. Você deve citar ("documentar") informações emprestadas, independentemente da forma em que as apresenta. Se você as cita diretamente, parafraseia ou resume—ainda assim é informação emprestada. Seja de um livro, artigo, um diagrama, uma tabela, uma página da web, um folheto de produto, um especialista que você entrevista pessoalmente—ainda assim é informação emprestada.
Sistemas de documentação variam de acordo com profissionais e áreas. Engenheiros usam o sistema IEEE, exemplos dos quais são mostrados ao longo deste capítulo. Outro sistema de documentação comumente utilizado é fornecido pela American Psychological Association (APA). Veja documentação para detalhes.
Numeração de Páginas
O estilo de numeração de páginas usado no design tradicional de documentação técnica difere do design contemporâneo principalmente pelo uso de números romanos minúsculos no material preliminar (tudo antes da introdução).
Nota: Documentos técnicos mais longos frequentemente usam o estilo de numeração de páginas conhecido como folio por capítulo ou dupla numeração (por exemplo, as páginas no Capítulo 2 seriam numeradas como 2-1, 2-2, 2-3, e assim por diante). Da mesma forma, tabelas e figuras usariam esse estilo de numeração. Este estilo facilita o processo de adição e exclusão de páginas.
Prompts de IA para Documentação Técnica
Listas de verificação, que normalmente não são 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 de cartas de apresentação ou seus componentes podem ser encontradas no manual online de redação técnica.
|
Promptes de IA para Techdocs Quando você quer que a IA avalie um projeto de escrita, apresente-se, diga à IA quem você é, 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 o Gemini verifique em sua avaliação. Aqui está um exemplo: Olá, IA. Eu sou David McMurrey, um estudante de cibersegurança no Austin Community College (Austin, Texas). Solicito que você avalie o seguinte documento técnico usando isso. livro didático online e as seguintes perguntas: |
Informações Relacionadas
TOC: Uma Ferramenta Organizacional Fundamental para Leitores
Agradeceria seus pensamentos, reações, críticas em relação a este capítulo: sua resposta—David McMurrey.
