在线技术写作：报告设计

我们仍在努力完成这一章节 -- 大卫

技术文档（包括手册、白皮书和指南）根据行业、专业或组织的不同而具有各种设计。本章展示了一种传统设计。如果您正在上技术写作课程，请确保本章中提供的设计是可以接受的。在科学、商业或政府背景下撰写技术文档时也是如此。

NotebookLM-generated infographic of this chapter NotebookLM生成的本章信息图表

注意：多年来，这本在线技术写作教材将报告泛泛地称为几乎所有包含技术信息的内容。但由于“报告”指的是一种特定类型的技术文档，因此必须改为通用的“技术文档”，简称为“techdoc”。

技术文档（技术文件的通用名称）与其他项目一样有规范。技术文档的规范涉及布局、组织和内容、标题和列表的格式、图形的设计等等。对技术文档要求结构和格式的好处在于，您或其他任何人都可以期待它们以熟悉的方式进行设计—您知道要寻找什么以及在哪里寻找。技术文档通常是匆忙阅读的—人们急于获取他们所需的信息、关键事实、结论和其他必需信息。标准的技术文档格式就像一个熟悉的社区。

当你分析技术文档的设计时，请注意某些部分的重复性。这种重复与人们阅读技术文档的方式有关。他们不会通篇阅读技术文档：他们可能会从执行摘要开始，跳来跳去，可能不会阅读每一页。你的挑战是设计技术文档，使这些读者无论阅读了多少内容或按何种顺序阅读，都能遇到你的关键事实和结论。

确保查看示例技术文档.

本章讨论了典型技术报告的标准组成部分。以下各节将指导您了解这些组件，指出关键特点。在您阅读和使用这些指南时，请记住这些只是指南，而不是命令。不同的公司、行业和组织有自己不同的技术文档指南，您需要根据这些指南以及这里提供的指南调整您的实践。

传输信息

传送信息可以是封面信（或备忘录）或电子邮件。纸质信件（或备忘录）要么用回形针附在技术文档的外面，要么装订在技术文档内部。电子邮件包含指向技术文档的链接或附加有技术文档。它是来自你—技术文档写作者—发送给接收者的沟通，即请求技术文档的人，可能还会为你的专业咨询支付费用。基本上，它的内容是“好的，这就是我们约定我在某日期之前完成的技术文档。简要来说，里面包含了这个和那个，但不涉及这个或那个。如果符合你的需求，请告诉我。”传送信息解释了背景—导致技术文档产生的事件。它包含有关技术文档的信息，而这些信息不应出现在技术文档中。

Business letter and email versions of transmital message
传送函和传送消息的示例。

在传递信的示例中，注意标准商业信函格式。如果你写内部技术文档，请使用备忘录格式；在这两种情况下，内容和组织都是相同的：

第一段。引用技术文档的名称，并将其用斜体表示。它还提到了撰写技术文档的协议日期。

中间段落。专注于技术文档的目的，并简要概述技术文档的内容。

最后一段。鼓励读者如果有问题、意见或关注事项可以联系。最后以良好的祝愿结束，表达希望读者对技术文档满意。

与技术文档中的其他元素一样，您可能需要根据具体情况修改此消息（或备忘录）的内容。例如，您可能想添加另一段，列出希望读者在审阅技术文档时考虑的问题。

封面、标题页和标签

如果您的技术文档超过十页，请将其以某种方式装订，并为封面创建标签。

封面

封面为技术文档提供了坚固、专业的外观以及保护。您可以选择多种类型的封面。请记住以下提示：

完全不可接受的是那些左边有塑料滑套的透明（或彩色）塑料保护套。这些就像是大学一年级英语课的产物；而且使用起来非常麻烦—读者必须努力保持它们打开，并且要应对它们产生的静电。
边缘可接受的是那些在页面上打孔、装入页面并弯曲支架的封面。如果使用这种类型，请在左边缘留出额外的半英寸边距，以便读者不必费力地撬开页面。当然，这种类型的封面会导致页面无法平放：读者必须抓住可用的物体或使用身体的不同部位来压住页面。
到目前为止，最好的封面是那些能够让技术文档自行翻开的（见下一节中的插图）。技术文档能在你的腿上或桌上平摊开来，真是太让人放松了。这种类型使用塑料螺旋装订，并采用厚卡纸作为封面。请向当地的复印店咨询这些类型的装订；它们价格便宜，并能提升你工作的专业性。请查看下面塑料螺旋装订的模拟示例。

通常不太受欢迎的是活页笔记本或环形文件夹。这些对短期技术文档来说太笨重，页面上的孔容易撕裂。当然，环形文件夹便于更换页面；如果你的技术文档会这样使用，那么它是一个不错的选择。在“高端”上，过于花哨的封面有着仿皮革外观和金色装饰。避免使用它们，保持简单、朴素和实用。

标题页

在最简单的情况下，技术文档标题是封面上内容的复制—可能添加了一些细节。

查看标题页摘要与执行摘要.

摘要和执行摘要

大多数技术文档至少包含一个摘要—有时两个，在这种情况下，摘要发挥不同的作用。摘要概述技术文档的内容，但不同类型的摘要以不同的方式进行概括：

描述性摘要。此类型提供了技术文档的目的和内容概述。在某些技术文档设计中，描述性摘要位于标题页的底部，如下所示：

描述性摘要通常，它被放置在标题页上（而不是封面页）。
执行摘要。另一种常见类型是执行摘要，它同样总结了技术文档中的关键事实和结论。请参见下面的示例。就好像你用黄色荧光笔标记了技术文档中的关键句子，然后将它们提取到单独的一页，并编辑以提高可读性。通常，执行摘要的长度为技术文档的十分之一到二十分之一，技术文档通常为十到五十页。对于更长的技术文档（超过五十页），执行摘要不应超过两页。执行摘要的目的是提供技术文档的摘要——一种可以快速阅读的内容。

如果执行摘要、介绍和传递信息让你觉得重复，请记住，读者不一定是从技术文档的开头开始逐页阅读到最后。他们可能会跳来跳去：他们可能会浏览目录；通常会快速浏览执行摘要以获取关键信息和结论。他们可能只仔细阅读技术文档的某一部分或两部分，然后跳过其余部分。这些原因使得技术文档设计中包含一些重复，以确保读者无论从哪里切入技术文档，都能看到重要信息。

目录（首先出现）然后是执行摘要。

仅起始页码。尽管一些自动目录生成器显示页码范围，但标准只显示第一页的页码。
包含的标题级别。如上表所示，显示前两级标题，除非技术文档有很多副标题。目录应提供一种快速查找信息的方法。
间距和大写字母。注意上面的目录中文本项的缩进。一级标题使用全大写；二级标题每个主要单词首字母大写；三级标题使用句子风格的大写。
垂直间距。请注意，一级部分上下有额外的空白，这提高了可读性。

领导者点和右对齐的页码。 对于使用引导点和右对齐页码的传统目录：

右对齐。 在这个例子中，请注意，领导点“引导”到右对齐的页码。

领头点和右对齐的页码。

这个目录使用十进制编号样式来标识章节和节的编号，这在技术文档中很常见。本书中的其他部分仅对顶级章节使用大写罗马数字样式（见于）。

创建格式良好的目录有麻烦吗？请看创建一个专业外观的目录

逗号和页码。 如果不需要使用领导点格式，并且您希望避免它，可以使用这种普遍接受的格式：

3. 能源效率的关键原则，5

被动设计策略，6
主动能量系统，7
可再生能源整合, 9

4. 标准和认证，11

LEED，11
节能之星，12
生活建筑挑战，14

简单的目录文本，带逗号和页码。

图表目录

图表清单与目录有许多相同的设计考虑。读者使用图表清单来查找您技术文档中的插图、图解、表格和图表。

当同时有表格和图形时，会出现复杂情况。严格来说，图形是插图、绘画、照片、图表和图形。表格是单词和数字的行和列；它们不被视为图形。

对于包含大量图表的较长技术文档，创建单独的图表和表格列表。如果空间允许，可以将它们放在同一页面上，如下图所示。您可以将这两个列表合并在“图表和表格列表”标题下，并根据下面的示例标识各项为图或表。

介绍

任何技术文档的一个基本要素是其介绍—确保您清楚其真实目的和内容。在技术文档中，介绍部分为读者准备阅读技术文档的主体内容。查看介绍讨论写作引言。

查看这个介绍示例：

图表清单，随后是引言。

如果没有表格，请改为“图表清单”。在技术写作课程中，询问您的老师是否要求使用小数编号样式为标题。

技术文档正文

技术文档的主体当然是技术文档的主要文本，即引言和结论之间的部分。下面展示的是示例页面。

标题

在所有但最短的技术文档（两页或更少）中，使用标题来标识涵盖的不同主题和子主题。标题使读者能够快速浏览您的技术文档，并在您提供他们想要的信息的地方深入了解。请参见标题关于标题的指南。

项目符号和编号列表

在技术文档中，适当时也使用项目符号、编号和双栏列表。列表有助于强调关键点，使信息更易于理解，并打破密集的文本块。见列表有关列表的指南。

符号、数字和缩写

技术讨论通常包含许多符号、数字和缩写。请记住，在技术领域，使用数字与使用文字的规则是不同的。关于将所有小于10的数字写出的旧规则并不总是适用于技术文档。数字与文字以供参考。）

除来自技术文档的主体。

在技术写作课程中，问您的教师小标题是否必须使用十进制编号风格。此外，可能需要不同的文档系统—而不是IEEE，那是为工程师设计的。

图形和图表标题

在技术文件中，您可能需要图纸、图表、表格和图形。这些不仅能更有效地传达某些信息，还能为您的技术文档增添专业性和权威感。如果您从未在文档中插入这些类型的图形，实际上有一些相对简单的方法可以做到——您不需要成为专业的平面设计师。有关将图形添加到文档的策略，请参见。图形. 有关如何在 s 中添加表格的策略，请参见表格.

交叉引用

您可能需要在您的技术文档中指出与之密切相关的信息，或其他具有相关信息的信息源。这些被称为 交叉引用例如，他们可以将读者从机制的讨论指向对其的插图。他们可以将读者指向附录，其中提供了有关主题的背景信息（这些背景信息不适合放在正文中）。他们还可以将读者指向你技术文档之外的其他信息，包括与您的内容相关的文章、技术文档和书籍。当您创建交叉引用时，请遵循以下指导方针。交叉引用.

结论

对于大多数技术文档，您需要包含一个最后的部分。当您规划技术文档的最后部分时，请考虑它在与技术文档的其余部分的关系中可以执行的功能。最后部分的想法在结论.

附录

附录是指在结论后面的额外部分。附录中可以放什么？—任何不适合放在技术文档主体中的内容，但又不能完全省略的内容。附录通常用于存放大型数据表、大块示例代码、展开地图、对技术文档主体过于基础或过于高级的背景信息，或不适合放在主体中的大型插图。任何你觉得对技术文档主体来说过于庞大，或可能分散注意力并打断文档流的内容，都很适合放在附录中。请注意，每个附录都有一个字母（A、B、C，以此类推）。

信息来源

记录您的信息来源与在职业中建立、维护和保护您的信誉密切相关。您必须引用（“记录”）所借用的信息，无论您以何种方式呈现它。无论您是直接引用、转述还是总结，它_—_仍然是借用的信息。无论它来自书籍、文章、图表、表格、网页、产品手册，还是您亲自采访的专家_—_这仍然是借用的信息。

文档系统因专业和领域而异。工程师使用IEEE系统，本章中展示了一些例子。另一种常用的文档系统是由美国心理学协会（APA）提供的。请参见文档详细信息。

页码编号

传统技术文档设计中使用的页码样式与现代技术文档设计的主要区别在于前言部分（介绍之前的所有内容）使用小写罗马数字。

技术文档中的所有页面（不包括前后封面）都有编号；但是某些页面上没有显示数字。
在现代设计中，文档中的所有页面使用阿拉伯数字；在传统设计中，引言之前的所有页面（正文的第一页）使用小写罗马数字。
在特殊页面，例如封面和介绍的第一页，不显示页码。
页码可以放在页面的几个区域之一。通常，最佳和最简单的选择是将页码放在页面底部中央（请记得在特殊页面上隐藏它们）。
如果您将页码放在页面顶部，则必须在章节或部分开启时隐藏它们，那里有标题或标题位于页面顶部。

注意：较长的技术文档通常使用称为“按章节编号”或“双重编号”的页码风格（例如，第二章的页面将编号为 2-1，2-2，2-3，依此类推）。类似地，表格和图形也会使用这种编号风格。这种风格简化了添加和删除页面的过程。

科技文档的AI提示

待检查清单通常不会被阅读，但经过一些修改，可以作为AI提示的来源。复制以下内容，将其粘贴到像谷歌的Gemini这样的AI系统中，看看你可能错过了什么。

注意：所有关于申请信内容、格式、风格或其组成部分的参考信息可以在这里找到。在线技术写作教材.

技术文档的AI提示

当您希望人工智能评估一个写作项目时，请先介绍自己，告诉人工智能您是谁，以及您想要什么。为人工智能提供一个评估的参考点，比如一本在线教科书。然后发布您希望Gemini在评估中检查的内容。以下是一个示例：

您好，人工智能。我是大卫·麦克穆雷，奥斯汀社区学院（德克萨斯州奥斯汀）的一名网络安全学生。我请求您评估以下技术文件。在线教科书和以下问题：

技术文档（报告）是否包含以下内容（按此顺序正确格式化）：传输消息；标题页；目录；图表清单，表格，或者两者；引言；正文部分（章节）；附录（如有需要）；信息来源；封底（如有需要）。详细信息，请参见技术文档设计.
虽然它可以很聪明和有趣，但该技术文档的标题是否足够明确地表明其主题？有关详细信息，请参见技术文档标题.
如果目录和图表（和表格）使用引导点，页码是否右对齐？如果目录和图表（和表格）在页面右侧包括页码，是否使用引导点？详情请见目录和图表（表格）列表.
引言是否充分表明了技术文档的主题、目的和预期读者？它是否提供了将要涵盖的子主题列表及范围的指示（未涵盖的内容）？有关详细信息，请参见介绍.
该技术文档是否包含足够的细节、具体信息、例子—以解释这些主张和一般性内容？
考虑到主题、目的和受众，这份技术文档中是否缺少任何重要内容？是否有任何内容是不必要的？这份技术文档中是否有任何信息在技术上不正确？是否缺少任何重要的技术信息？
在本技术文档中，是否包含任何明显借用的信息而没有以任何方式记录？
引文（信息来源列表中项目的引用）是否按照APA、MLA或修改过的IEEE风格出现在技术文档正文中？信息来源列表中的项目是否按照APA、MLA或修改过的IEEE风格格式化？详细信息，请参见文档：借用的信息来源.
所有表格和非装饰性图形是否都包含描述性标题（说明）和来源（如有需要）？有关详细信息，请参见表格标题.
所有表格和非装饰性图形尽可能靠近其相关文本出现吗？
在表格和非装饰性图形之前是否会发生简要说明的交叉引用？有关详细信息，请参见解释性交叉引用.
技术文档的主体中是否使用标准格式的标题和子标题？详细信息请参见标题.
技术文档的主要章节在印刷版本中是否从新的一页开始？
编号的垂直列表用于按要求顺序排列的列表项吗？项目符号的垂直列表用于没有要求顺序的列表项吗？所有列表前都使用引言吗？有关详细信息，请参见垂直列表.
直接引用是否注明了出处，并且出处的标点是否正确？所有直接引用、总结和意译是否按APA、MLA或修改后的IEEE格式正确引用？有关详细信息，请参见引用与归属.
该技术文档的文本是否没有语法、用法和标点错误？有关详细信息，请参见常见语法、用法、拼写问题.
该技术文档的内容是否没有冗余和其他句子风格错误？详情请查看冗长，其他句子格式问题.
此技术文档是否能被其目标受众理解（如传送消息和介绍中所述）？有关详细信息，请参见受众分析，看看翻译技术内容.
AI，给我的技术文档评估打一个从100到55的分数。

技术文档设计

提供一个预期的结构和设计。

本节内容

主索引