Por favor, clique aqui para ajudar David McMurrey pagar por hospedagem na web:
Doe qualquer quantia pequena que puder!
A Redação Técnica Online continuará gratuita.
Documentos técnicos (incluindo manuais, artigos e guias) têm 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 científico, empresarial ou governamental.
Infográfico gerado pelo NotebookLM deste capítulo
Nota: Por anos, este livro didático de escrita técnica online referia-se genericamente a relatórios como praticamente qualquer coisa que contivesse informações técnicas. Mas como "relatório" se refere a um gênero específico de documento técnico, a mudança precisava ser feita para o genérico "techdoc", abreviação de documento técnico.
Os 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 requeridos 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 chegar à informação que precisam, os fatos chave, as conclusões e outros essenciais. Um formato padrão de techdoc é como um bairro familiar.
Ao analisar o design de um techdoc, note como algumas seções são repetitivas. Essa duplicação está relacionada à maneira como as pessoas leem techdocs. Elas não leem techdocs do início ao fim: podem começar pela sinopse executiva, pular trechos 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 leiam.
Certifique-se de ver o exemplo de techdocs.
Os componentes padrão do típico relatório técnico são discutidos neste capítulo. As seções a seguir o guiarão por cada um desses componentes, destacando as características principais. Ao ler e usar estas diretrizes, lembre-se de que são orientações, não comandos. Diferentes empresas, profissões e organizações têm suas próprias diretrizes variadas para documentos técnicos—você precisará adaptar sua prática a essas, bem como às apresentadas aqui.
Mensagem de Transmissão
A mensagem de envio é ou uma carta de apresentação (ou memorando) ou um e-mail. A carta física (ou memorando) está anexada ao exterior do documento técnico com um clipe de papel ou encadernada 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 redator do documento técnico—para o destinatário, a pessoa que solicitou o documento técnico e que pode até estar lhe pagando 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. Avise-me se atende às suas necessidades." A mensagem de envio explica o contexto—os eventos que levaram à elaboraçã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 remessa, observe o formato padrão de carta comercial. Se você escrever um documento técnico 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. Foca 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 techdoc satisfatório.
Assim como em qualquer outro elemento de 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 gostaria que os leitores considerassem ao revisar o documento técnico.
Capa, Página de Título e Rótulo
Se o seu documento técnico tiver mais de dez páginas, encaderne-o de alguma forma e crie um rótulo para a capa.
Capas
As capas dão aos documentos técnicos 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 são como algo saído de uma aula de inglês de calouros; além disso, são irritantes de usar—os leitores devem lutar para mantê-las abertas e lidar com a eletricidade estática que geram.
- Marginalmente aceitáveis são as capas para as quais você perfura buracos 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 separar as páginas à força. Claro, esse tipo de capa impede que as páginas fiquem planas: os leitores devem pegar 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 no seu colo ou na sua mesa. Esse tipo usa uma espiral plástica para a encadernação e papel cartão grosso para as capas. Consulte a sua gráfica local para esses tipos de encadernações; são baratas e acrescentam ao profissionalismo do seu trabalho. Veja o exemplo simulado de uma encadernação em espiral plástica a seguir.
Geralmente, são menos preferíveis os cadernos de folhas soltas ou as pastas com argolas. Elas são muito volumosas 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 é dessa forma que seu documento técnico será usado, então é uma boa escolha. No "alto nível" estão as capas excessivamente sofisticadas com seu aspecto de couro sintético e detalhes em dourado. Evite-as—mantenha-o simples, prático e funcional.
Página de Título
Na 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 em torno das informações do rótulo. Imprima, depois vá a uma copiadora e mande fotocopiar diretamente na capa do techdoc.
Não há muitas informações 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 transmissão e capa do documento técnico (com etiqueta de capa).
Resumo e Sumário Executivo
A maioria dos documentos técnicos técnicos contém pelo menos um resumo—às vezes dois, caso em que os resumos desempenham papéis diferentes. Resumos resumem o conteúdo de um doc técnico, mas os diferentes tipos o fazem de maneiras diferentes:
- Resumo descritivo. Esse 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, como mostrado a seguir:
Resumo descritivo. Tradicionalmente, é 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ê tivesse usado um marcador amarelo para destacar as frases-chave no documento técnico e, em seguida, as extraísse para uma página separada e as editasse para melhor legibilidade. Normalmente, os resumos executivos têm de um décimo a um vigésimo do comprimento dos 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 transmissão lhe parecerem repetitivos, lembre-se de que os leitores não começam necessariamente pelo início de um documento técnico e leem página por página até o final. Eles pulam para outras partes: podem dar uma olhada no índice; geralmente, passam rapidamente pelo resumo executivo em busca de fatos e conclusões principais. Podem ler com atenção apenas uma ou duas seções do corpo do documento técnico e depois 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 mergulhem no documento técnico.
Índice (que vem primeiro) depois o resumo executivo.
Tabela de Conteúdos
Qualquer formato de tabela de conteúdo (TOC) que você use, 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 índice acima, exiba os dois primeiros níveis de cabeçalhos, a menos que o documento técnico tenha muitos subtítulos. O índice deve fornecer uma maneira rápida de encontrar informações à primeira vista.
- Espaçamento e capitalização. Observe como os itens de texto no índice acima estão recuados. 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 estilo 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.
- Todas as páginas do techdoc (dentro, mas excluindo as capas frontal e traseira) estão numeradas; mas em algumas páginas, os números não estão exibidos.
- No design contemporâneo, todas as páginas do documento usam algarismos arábicos; no design tradicional, todas as páginas antes da introdução (primeira página do corpo) usam algarismos 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 na parte inferior central da página (lembre-se de ocultá-los em páginas especiais).
- Se você colocar números de página 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 adequadamente) nesta ordem: mensagem de transmissão; página de título; índice; lista de figuras, tabelas ou ambos; introdução; seções do corpo (capítulos); apêndices (conforme necessário); fontes de informação; contracapa (se necessário). Para mais detalhes, veja Design de Techdoc.
- Embora possa ser inteligente 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) usam pontos de líder, os números da página estão alinhados à direita. Se o índice e a lista de figuras (e tabelas) incluem números da página na borda direita da página, os pontos de líder são usados? Para mais detalhes, veja Sumários e Lista de Figuras (Tabelas).
- A introdução indica adequadamente o tópico, o propósito e o público-alvo do documento técnico? Ela fornece uma lista de subtópicos a serem abordados e uma indicação do escopo (o que não está coberto)? Para detalhes, veja Introduções.
- Este techdoc contém detalhes adequados, especificidades, exemplos—qualquer coisa que seja necessária para explicar as afirmações, as generalidades?
- Considerando o tópico, o propósito e o público, há algum conteúdo vital faltando neste documento técnico? Algum conteúdo é desnecessário? Há alguma informação neste documento técnico que está tecnicamente incorreta? Alguma informação técnica crítica está faltando?
- Neste documento técnico, contém informações claramente emprestadas que não estão documentadas de nenhuma forma?
- As citações (referências a itens na lista de fontes de informação) ocorrem no corpo do techdoc formatadas 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 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 das tabelas.
- Todas as tabelas e figuras não decorativas ocorrem o mais perto possível de seu texto relevante?
- Os cross-references explicativos breves ocorrem 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 Cabeçalhos.
- As seções principais (capítulos) do documento técnico começam uma nova página nas versões impressas?
- Listas verticais numeradas são usadas para itens de lista em uma ordem requerida? Listas verticais com marcadores são usadas para itens de lista em nenhuma ordem requerida? Frases de introdução são usadas antes de todas as listas? Para mais detalhes, veja Listas verticais.
- As citações diretas estão atribuídas e as atribuições estão corretamente pontuadas? Todas as citações diretas, resumos e paráfrases estão devidamente citados de acordo com o estilo APA, MLA ou IEEE modificado? Para mais detalhes, consulte Citações e atribuições.
- O texto do techdoc está livre de erros gramaticais, de uso e de pontuação? Para mais detalhes, veja Problemas Comuns de Gramática, Uso e Ortografia.
- O texto do techdoc está livre de prolixidade e outros erros de estilo de frase? Para mais detalhes, veja Verborragia, outros problemas de estilo frasal.
- Este documento técnico pode ser compreendido pelo seu público-alvo (conforme indicado na mensagem de envio 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 documento técnico, atribua uma nota numérica de 100 a 55).
Pontos de liderança e números de página alinhados à direita. Para o TOC tradicional que usa pontos guia e números de página alinhados à direita:
Alinhamento à direita. Neste exemplo, note que os pontos de liderança "levam" para fora os números das páginas 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 dos capítulos e seções, o que é comum em documentos técnicos. Outros neste livro utilizam o estilo de numeração romana maiúscula apenas para os capítulos de nível superior (veja).
Problemas para criar um índice formatado corretamente? 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 amplamente 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 de Edifício Vivo, 14 |
Lista de Figuras e Tabelas
A lista de figuras possui muitas das mesmas considerações de design que o índice. Os leitores utilizam 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. Estritamente falando, 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. Coloque-as juntas na mesma página se caber, como 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, conforme feito na ilustração abaixo.
Introdução
Um elemento essencial de qualquer techdoc é sua introdução—certifique-se de que você esteja claro sobre seu verdadeiro propósito e conteúdo. Em uma techdoc, a introdução prepara o leitor para ler o corpo principal da techdoc. Veja apresentações para uma discussão sobre como escrever 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 escrita técnica, pergunte ao seu instrutor se o estilo de numeração decimal para cabeçalhos é 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. Abaixo estão ilustradas páginas de exemplo.
Títulos
Em todos os techdocs, exceto os mais curtos (duas páginas ou menos), use cabeçalhos para separar os diferentes tópicos e subtópicos abordados. Os cabeçalhos permitem que os leitores passem os olhos pelo seu techdoc e mergulhem nos pontos em que você apresenta informações que desejam. Veja títulos para diretrizes sobre cabeçalhos.
Listas com Marcadores e Numeradas
No corpo de um documento técnico, também use listas com marcadores, numeradas e em duas colunas, quando apropriado. Listas ajudam a enfatizar pontos-chave, a tornar a informação mais fácil de seguir e a quebrar blocos de texto contínuos. 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 velha regra sobre 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 documento técnico.
Em um curso de escrita 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. Esses elementos 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 extra de profissionalismo e autoridade. Se você nunca inseriu esse tipo de gráfico em um documento, há 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 a s, veja gráficos. Para estratégias de adição de tabelas a s, veja mesas.
Referências Cruzadas
Você pode precisar direcionar os leitores para informações estreitamente relacionadas dentro dos seus techdos, ou para outras fontes de informação que tenham informações relevantes. Estas são chamadas de referências cruzadas. Por exemplo, eles podem direcionar os leitores da discussão de um mecanismo para uma ilustração dele. Eles podem apontar os leitores para um apêndice onde é fornecido um fundo sobre um tópico (um fundo que simplesmente não se encaixa 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. Ao planejar a seção final do seu techdoc, pense nas funções que ela pode desempenhar em relação ao restante do techdoc. Ideias para seções finais são apresentadas em conclusões.
Apêndices
Apêndices são aquelas 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 pode ser deixada de fora do documento técnico como um todo. O apêndice é comumente utilizado 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 que é grande demais para a parte principal do documento técnico ou que você acha que seria distraente e interromperia o fluxo do documento técnico é uma boa candidata para um apêndice. Observe que cada um recebe 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 ou formato em que você as apresenta. Seja citando diretamente, parafraseando ou resumindo—ainda assim é informação emprestada. Seja ela proveniente 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.
Os sistemas de documentação variam de acordo com os profissionais e áreas. Engenheiros utilizam o sistema IEEE, exemplos do qual 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 mais detalhes.
Numeração de Páginas
O estilo de numeração de páginas utilizado no design de techdoc tradicional difere do design de techdoc contemporâneo principalmente pelo uso de números romanos minúsculos na parte preliminar (tudo antes da introdução).
Nota: Documentos técnicos mais longos costumam usar o estilo de numeração de página conhecido como folio-por-capítulo ou dupla numeração (por exemplo, as páginas no Capítulo 2 seriam numeradas 2-1, 2-2, 2-3, e assim por diante). Da mesma forma, tabelas e figuras usariam esse estilo de numeração. Esse estilo facilita o processo de adicionar e excluir páginas.
Promptes de IA para Techdocs
Checklists, que normalmente ficam sem ler, 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 de cartas de apresentação ou seus componentes podem ser encontradas no livro didático de escrita técnica online.
|
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 avaliações, como um livro didático online. Em seguida, poste 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ção Relacionada
TOC: Uma Ferramenta Organizacional Chave para Leitores
Agradeceria seus pensamentos, reações e críticas em relação a este capítulo: sua resposta—David McMurrey.
