Por favor, clique aqui para ajudar David McMurrey pagar pela hospedagem de sites:
Doe qualquer quantia que puder!
A Redação Técnica Online continuará gratuita.
Documentos técnicos (incluindo manuais, artigos técnicos e guias) têm várias 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 se referiu 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 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 cabeçalhos 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 obter as informações de que precisam, os fatos principais, as conclusões e outros elementos 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 tem a ver com a forma como as pessoas leem techdocs. Elas não leem techdocs de forma linear: podem começar pelo resumo executivo, pular partes e provavelmente não lerão todas as páginas. Seu desafio é projetar techdocs de modo que esses leitores encontrem seus fatos e conclusões-chave, independentemente de quanto do techdoc lerem 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 seguintes orientam você através de cada um desses componentes, destacando as características principais. Ao ler e usar essas diretrizes, lembre-se de que são diretrizes, não mandamentos. Empresas, profissões e organizações diferentes 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 transmissão é um 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 está 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 pagando por 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 isto ou aquilo. Deixe-me saber se atende às suas necessidades." A mensagem de transmissão 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 envio, observe o formato padrão de carta comercial. Se você escrever um documento técnico interno, use o formato de memorando; em qualquer caso, o conteúdo e a organização são os mesmos:
Primeiro parágrafo. Cite 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 dá 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. Encerra com um gesto de boa vontade, expressando a esperança de que o leitor ache o techdoc satisfatório.
Como com qualquer outro elemento em um documento técnico, pode ser necessário 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 enquanto revisam o documento técnico.
Capas, Página de Rosto e Rótulo
Se o seu documento técnico tiver mais de dez páginas, encaderne-o de alguma forma e crie uma etiqueta para a capa.
Capa
As capas conferem 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 parecem algo de um curso de inglês para calouros; além disso, são frustrantes 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 furos nas páginas, coloca 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 tenham que 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 techdocs fiquem abertos sozinhos (veja a ilustração na próxima seção). Que alívio para um techdoc ficar aberto em seu colo ou na sua mesa. Esse tipo utiliza uma espiral de plástico para a encadernação e papel cartão grosso para as capas. Consulte a copiadora local para esses tipos de encadernações; elas são baratas e acrescentam um toque profissional ao seu trabalho. Veja o exemplo simulado de uma encadernação com espiral de plástico a seguir.
Geralmente, são menos preferíveis os cadernos de folhas soltas ou os fichários. Eles são muito volumosos para documentos técnicos curtos, e os furos das páginas tendem a rasgar. Claro, o fichário facilita a troca de páginas; se é assim que seu documento técnico será utilizado, então é uma boa escolha. No "alto nível" estão as capas excessivamente elegantes com aparência de couro sintético e detalhes dourados. Evite-as—mantenha tudo simples, discreto e funcional.
Página de Título
Em sua forma mais simples, o título de um techdoc é uma cópia do que está na capa—possivelmente com alguns detalhes adicionais.
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. É uma etapa 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 peça para fotocopiar diretamente na capa do techdoc.
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 os 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, caso em que os resumos desempenham papéis diferentes. Resumos resumem o conteúdo de um documento técnico, mas os diferentes tipos o fazem de maneiras diferentes:
- Resumo descritivo. Esse tipo fornece uma visão geral do propósito e do conteúdo 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. 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ê usasse um marcador amarelo para destacar as frases-chave no documento técnico e, em seguida, as transferisse todas para uma página separada e as editasse para 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, acima 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 parecerem 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 fim. Eles pulam: podem analisar o índice; geralmente folheiam o resumo executivo em busca de fatos e conclusões importantes. Podem ler cuidadosamente 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 mergulhem no documento técnico.
Índice (o que vem primeiro) então o resumo executivo.
Índice
Independentemente do formato da 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. Como mostrado no TOC acima, exiba os dois primeiros níveis de cabeçalhos, a menos que o techdoc tenha muitos subtítulos. O TOC deve fornecer uma maneira rápida de encontrar informações rapidamente.
- Espaçamento e capitalização. Note como os itens de texto no índice acima estão alinhados. Títulos de primeiro nível usam letras maiúsculas; títulos de segundo nível usam letras maiúsculas no início de cada palavra principal; títulos de terceiro nível usam letras minúsculas em 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 frontal e traseira) 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 utilizam números arábicos; no design tradicional, todas as páginas antes da introdução (primeira página do corpo do ) utilizam números romanos minúsculos.
- 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 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 esteja 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; índice; 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 detalhes, consulte Design de Techdoc.
- Embora possa ser inteligente e divertido, o título do documento técnico indica adequadamente seu assunto? Para detalhes, veja Títulos de documentos técnicos.
- Se o índice e a lista de figuras (e tabela) utilizam pontos de liderança, os números das páginas estão alinhados à direita. Se o índice e a lista de figuras (e tabela) incluem números de página na borda direita da página, os pontos de liderança são usados? Para detalhes, veja Índices 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 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 generalizações?
- Considerando o tópico, o propósito e o público, há algum conteúdo vital faltando neste documento técnico? Há conteúdos desnecessários? Alguma informação neste documento técnico está tecnicamente incorreta? Alguma informação técnica crítica está faltando?
- 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 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 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 das tabelas.
- Todas as tabelas e figuras não decorativas ocorrem o mais próximo possível de seu texto relevante?
- As referências cruzadas explicativas breves ocorrem antes das tabelas e figuras não decorativas? Para detalhes, veja Referências cruzadas explicativas.
- Um formato padrão de cabeçalhos e subtítulos é usado no corpo do techdoc? Para mais detalhes, veja Cabeçalhos.
- As seções principais (capítulos) do techdoc começam em uma nova página nas versões impressas?
- As listas verticais numeradas são usadas para itens em uma ordem obrigatória? As listas verticais com marcadores são usadas para itens em nenhuma ordem obrigatória? As introduções são usadas antes de todas as listas? Para detalhes, veja Listas verticais.
- As citações diretas são atribuídas e as atribuições estão corretamente pontuadas? Todas as citações diretas, resumos e paráfrases estão devidamente citadas de acordo com o estilo APA, MLA ou IEEE modificado? Para detalhes, veja Citações & atribuições.
- O texto do documento técnico 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 techdoc está livre de prolixidade e outros erros de estilo de frase? Para mais detalhes, veja Wordiness, 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 documento técnico, atribua uma nota numérica de 100 a 55.
Pontos de líder e números de página alinhados à direita. Para o TOC tradicional que utiliza pontos de líder e números de página alinhados à direita:
Alinhamento à direita. Neste exemplo, observe que os pontos de liderança "levam" para fora os números da página que estão alinhados à direita.
Pontas de líder e números de página alinhados à direita.
Este índice usa 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 usam o estilo de numeração romana maiúscula apenas para os capítulos de nível superior (ver ).
Problemas para criar um TOC bem formatado? Veja Crie um TOC com aparência profissional
Vírgulas e números de página. Se um formato de líder em pontos 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 de Edifícios Vivos, 14 |
Lista de Figuras e Tabelas
A lista de figuras tem muitas das mesmas considerações de design que o índice. Os leitores usam a lista de figuras para encontrar as ilustrações, diagramas, tabelas e gráficos no 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 tabelas. 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, 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 documentação técnica é sua introdução—certifique-se de que você está 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, torne-o "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.
Cabeçalhos
Em todos, exceto nos techdocs mais curtos (duas páginas ou menos), use headings para marcar os diferentes tópicos e subtópicos abordados. Os headings permitem que os leitores façam uma leitura dinâmica do seu techdoc e mergulhem nos pontos onde você apresenta informações que eles desejam. Veja títulos para diretrizes sobre títulos.
Listas com Marcadores e Numeradas
No corpo de um documento técnico, também utilize listas com marcadores, numeradas e de duas colunas onde apropriado. As listas ajudam a enfatizar pontos chave, a tornar as informações mais fáceis de seguir e a quebrar paredes sólidas 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 numerais 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 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.
Títulos de Gráficos e 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ções de maneira mais eficiente, mas também conferem ao seu documento técnico uma aparência adicional de profissionalismo e autoridade. Se você nunca inseriu esse tipo de gráfico em 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 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 de seus techdos, ou para outras fontes de informação que tenham dados relevantes. Isso é chamado 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 fornecidos antecedentes 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 cross-referências.
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
Os 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 blocos de código de exemplo, mapas dobráveis, informações de fundo que são muito básicas ou muito avançadas para o corpo do documento técnico, ou ilustrações grandes que simplesmente não cabem no corpo do . Qualquer coisa que você considere muito grande para a parte principal do documento técnico ou que você acha que seria distractora e interromperia o fluxo do documento técnico é uma boa candidata para um apêndice. Note 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 do formato em que você as apresenta. Seja se você as cita diretamente, parafraseia ou resume—ainda assim é informação emprestada. Seja ela proveniente de um livro, artigo, diagrama, tabela, página da web, folheto de produto, um especialista que você entrevista pessoalmente—ainda assim é informação emprestada.
Os sistemas de documentação variam de acordo com profissionais e áreas. Engenheiros usam 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 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 folho-por-capítulo ou dupla enumeraçã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.
Promptes de IA para Techdocs
Listas de verificação, que geralmente 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 aplicação ou seus componentes podem ser encontradas no livro didático de redação 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ê é e o que deseja. Dê à IA um ponto de referência para fazer avaliações, como um livro didático online. Então, poste o que você quer 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). Eu peço que você avalie o seguinte documento técnico usando isso livro didático online e as seguintes perguntas: |
Informações Relacionadas
Índice: Uma Ferramenta Organizacional Chave para Leitores
Agradeceria suas opiniões, reações e críticas em relação a este capítulo: sua resposta—David McMurrey.
