请点击此处以提供帮助 大卫 麦克穆雷 为网站托管付费:
请捐出您能提供的任意小额款项 !
在线技术写作将继续免费.
技术文档（包括手册、白皮书和指南）的设计因行业、职业，或组织而异。 本章向你展示了一种传统的设计。 如果你正在参加一门技术写作课程，请确保本章所呈现的设计是可接受的。 如果你在科学、商业，或政府环境中撰写技术文档，情况亦然。
本章由 NotebookLM 生成的信息图
注意: 多年来，这本在线技术写作教科书把报告泛指为几乎任何包含技术信息的东西。但由于“report”指的是一种特定类型的技术文档，必须将通用称呼改为“techdoc,”，即 technical document（技术文档）的缩写。
Techdocs（技术文档的通用名称）像任何其他项目一样有规范。技术文档的规范涉及版面布局、组织与内容、标题和列表的格式、图形的设计，等等。对技术文档要求结构和格式的好处在于，你或其他任何人都可以期望它们以一种熟悉的方式设计—你知道要寻找什么以及在哪里寻找。技术文档通常是在匆忙中阅读的—人们急于获取所需的信息、关键事实、结论和其他要点。标准的技术文档格式就像一个熟悉的街区。
当你分析一份 techdoc 的设计时，注意某些章节是多么重复。这种重复与人们阅读 techdoc 的方式有关。他们不会顺序通读 techdoc：他们可能先从执行摘要开始，随意跳读，并且很可能不会阅读每一页。你的挑战是设计 techdoc，使这些读者无论读到多少内容或以何种顺序阅读，都能遇到你的关键事实和结论。
一定要看看 示例 技术文档.
本章讨论了典型技术报告的标准组成部分。 下面的各节将引导你逐一了解这些组成部分，并指出关键特征。 在你阅读并使用这些指南时，请记住，这些是指南，而不是命令。 不同的公司、职业和组织对 techdocs—you'll 有各自不同的准则，你需要将自己的实践既适应那些准则，也适应这里提出的准则。
传递信息
传递信息要么是一封附信（或备忘录），要么是一封电子邮件。 实体信件（或备忘录）要么用回形针夹在技术文档的外面，要么装订在技术文档内部。 电子邮件包含指向技术文档的链接或附带技术文档。 它是从你—技术文档作者—到接收者的一次沟通，接收者是请求该技术文档的人，甚至可能为你的专业咨询支付费用。 本质上，它的意思是 “好，这是我们约定我在某个约定的日期前完成的技术文档。简要地说，它包含这些内容，但不包括那些内容。请告诉我它是否满足你的需求。” 传递信息解释了背景—导致该技术文档产生的事件。 它包含了关于该技术文档但不适合出现在技术文档正文中的信息。
转交函和转交信息示例.
在转交信函的示例中，请留意标准的商务信函格式。如果你撰写内部技术文档，应改用备忘录格式；无论采用哪种，内容和组织结构都是相同的：
第一段。 引用该技术文档的名称，并将其以斜体表示。还提及同意撰写该技术文档的日期。
中间段落. 关注技术文档的目的，并简要概述技术文档的内容。
最后一段. 鼓励读者在有问题, 意见或疑虑时与我们联系. 结尾以善意的表示, 表达希望读者对该技术文档感到满意.
和技术文档中的任何其他元素一样，你可能需要根据具体情况修改此消息（或备忘录）的内容。例如，你可能想添加另一个段落，列出你希望读者在审阅技术文档时考虑的问题。
封面, 书名页 和 标签
如果你的技术文档超过十页，请用某种方式装订并为封面制作标签。
封面
封面不仅能让技术文档看起来结实、专业，还能提供保护。 你可以从多种封面类型中选择。 请记住以下提示：
- 完全不能接受的是那种左侧边缘带有塑料套的透明（或彩色）塑料封套。这些就像大一英语课的东西；而且使用起来令人恼火—读者不得不费力把它们撑开，还要应付它们产生的静电。
- 勉强可以接受的是那种在书页上打孔、装入页面并折下金属夹钉的封面。 如果使用这种类型，请在左侧边缘多留半英寸的边距，这样读者就不用把页面撬开。 当然，这种封面会使页面无法平摊：读者必须抓住手边的物品或用身体的各种部位压住页面。
- 到目前为止，最好的封面是那些能让技术文档自行摊开（见下一节的插图）。能够让技术文档摊开在你的膝上或桌上，真是莫大的宽慰。这种类型采用塑料螺旋作装订，封面用厚卡纸。向你当地的复印店咨询这类装订；它们价格低廉，并能提升你作品的专业感。下文为塑料螺旋装订的模拟示例。
标题页
在最简单的情况下, 技术文档标题就是封面上的内容副本—可能只是加了几处细节.
请看一下标题页 摘要与执行摘要.
标签
请务必为您的技术文档封面设计一个标签。 这是一些技术文档作者会忘记的步骤。 没有标签，技术文档就无名；它会被忽视。
创建标签的最佳方法是使用您的文字处理软件在一张标准页面上设计一个标签，并在标签信息周围画一个图形框. 打印出来, 然后去复印店把它直接复印到技术文档封面上.
标签上写的不多：技术文档标题、你的名字、你所在组织的名称、技术文档跟踪编号和日期。标签没有标准要求，尽管你的公司或组织应该有自己的要求。（下面显示了一个技术文档标签的示例。）
转交函和技术文档封面（含封面标签）。
摘要 与 执行摘要
大多数技术文档至少包含一个摘要—有时是两个, 在这种情况下这些摘要扮演不同的角色。摘要概述了技术文档的内容, 但不同类型的摘要以不同的方式做到这一点:
- 描述性摘要. 这种类型提供了技术文档的目的和内容的概述. 在一些技术文档设计中, 描述性摘要被放置在标题页的底部, 如下所示:
描述性摘要. 传统上，它被放在书名页（不是封面）。 - 执行摘要. 另一个常见的类型是执行摘要，它也总结了技术文档中包含的关键事实和结论。参见下文所示的示例。就好像你用黄色荧光笔标出技术文档中的关键句子，然后把它们都抽取到单独的一页上并为可读性进行了编辑。通常，执行摘要的长度是十到五十页技术文档的十分之一到二十分之一。对于更长的技术文档（超过五十页），执行摘要不应超过两页。执行摘要的要点是提供一个可以快速阅读的技术文档—something的摘要。
如果执行摘要、引言和传达信息让你觉得有些重复，请记住，读者不一定会从技术文档的开头按页逐页读到结尾。他们会跳着看：他们可能会浏览目录；通常会略读执行摘要以获取关键事实和结论。他们可能只认真阅读技术文档正文中的一两个部分，然后跳过其余内容。出于这些原因，技术文档在设计时会包含一定程度的重复，以确保读者无论从何处进入文档都能看到重要信息。
目录（先出现） 然后是执行摘要.
目录
无论你使用哪种目录（TOC）格式，以下是常见的标准：
- 仅起始页码。 虽然一些自动 TOC 生成器会显示页码范围，标准是只列出起始页码。
- 要包含的标题级别。 如上方的目录（TOC）所示，显示前两级标题，除非该技术文档有大量子标题。目录应以一目了然的方式，便于快速查找信息。
- 间距 和 大小写. 注意上方目录中的文本项是如何缩进的。一级标题使用全大写；二级标题中每个主要单词的首字母大写；三级标题使用句式首字母大写。
- 垂直间距. 请注意，一级章节在上方和下方有额外的空白，这提高了可读性。
- 技术文档中的所有页面 (不含前后封面) 都有编号; 但在某些页面上, 编号未显示.
- 在现代设计中，整个文档的所有页面都使用阿拉伯数字；在传统设计中，介绍之前的所有页面（正文的第一页）使用小写罗马数字。
- 在特殊页面上, 例如标题页和导言的第一页, 页码不显示.
- 页码可以放在页面的多个区域之一。通常，最简单且最好的选择是将页码放在页面底部中央（记得在特殊页面上隐藏它们）。
- 如果你把页码放在页面顶部，当页面顶部有章节或小节的标题时，必须将页码隐藏。
- 该技术文档（报告）是否按以下顺序包含下列内容（格式正确）：递交函；标题页；目录；图目录、表目录或两者；引言；正文部分（章节）；附录（如需）；信息来源；封底（如需）。详情见 技术文档 设计.
- 虽然可以很机智和俏皮，但该技术文档的标题是否足以表明其主题？详情请见 技术文档 标题.
- 如果目录和图目录（以及表目录）使用前导点，页码是否右对齐。 如果目录和图目录（以及表目录）在页面右侧包含页码，是否使用前导点？ 有关详情，请参见 目录和图表（表格）清单.
- 引言是否充分表明该技术文档的主题、目的和预期读者？是否提供将要涵盖的子主题清单以及对 范围（未涵盖的内容）？ 有关详细信息，请参见 介绍.
- 这份技术文档是否包含足够的细节, 具体内容, 示例—以及解释这些断言和一般性说法所需的任何内容?
- 考虑到主题、目的和受众，这份技术文档是否缺少任何重要内容？ 有任何内容是不必要的吗？ 这份技术文档中有没有任何技术性错误？ 是否缺少任何关键的技术信息？
- 在这份技术文档中，是否包含任何明显借用且未以任何方式注明来源的信息？
- 引文（对信息来源列表中条目的引用）是否在技术文档正文中按照 APA、MLA 或修改后的 IEEE 风格出现？信息来源列表中的条目是否按照 APA、MLA 或修改后的 IEEE 风格格式化？详情请参见 文档: 借用的信息来源.
- 所有表格和非装饰性图表是否都包含描述性标题（图注）和来源（如需要）？有关详细信息，请参见 表格标题.
- 所有表格和非装饰性图形是否都尽可能靠近其相关文本出现？
- 在表格和非装饰性图形之前是否出现简短的说明性交叉引用？详情请参见 说明性交叉引用.
- 技术文档正文是否使用标准的标题和子标题格式？详情请参见 标题.
- 技术文档的主要部分 (章节) 在打印版中会另起一页吗？
- 在需要顺序的条目中是否使用编号的纵向列表？ 在没有顺序要求的条目中是否使用带项目符号的纵向列表？ 是否在所有列表之前使用引导语？ 对于详细信息，请参见 垂直列表.
- 直接引用是否注明了来源，且该注明的标点是否正确? 所有直接引用、摘要、释义是否均按照 APA, MLA, 或修改后的 IEEE 风格正确引用? 详情请参见 引文 & 署名.
- 这份技术文档的文本是否没有语法、用法和标点错误？详情请见 常见的语法, 用法, 拼写问题.
- 该技术文档的文本是否没有冗词赘句和其他句式错误？ 详情请参见 冗长，其他句子风格问题.
- 这份技术文档能被其目标读者（如传送信息和引言中所示）理解吗？详情请参见 受众分析, 并查看 翻译技术内容.
- 人工智能, 为了完成你对我的技术文档的评估, 请给出一个从100到55的数值评分).
引导点和右对齐的页码。 对于使用点状引导符并将页码右对齐的传统目录：
右对齐。 在 这个 例子, 注意，点线（leader dots）将右对齐的页码“引出”。
前导点和右对齐的页码。
此 TOC 对章节和小节的编号使用十进制编号样式，这在技术文档中很常见。书中其他部分仅在顶层章节使用大写罗马数字样式（参见 ）。
创建格式良好的目录有困难？参见 创建专业且美观的目录
逗号和页码。 如果不需要使用点引导格式，并且你希望避免它，你可以使用这种常见的格式：
|
3. 能源效率的关键原则, 5
被动式设计策略, 6
4. 标准与认证, 11主动能源系统, 7 可再生能源整合, 9
LEED, 11
能源之星, 12 活建筑挑战, 14 |
图表目录
图表清单在设计考虑方面与目录有许多相同之处. 读者使用图表清单来查找技术文档中的插图, 示意图, 表格, 和图表.
当同时存在表格和图形时，会出现复杂情况. 严格来说, 图形是插图, 绘画, 照片, 曲线图, 和图表. 表格是由文字和数字组成的行和列; 它们不被视为图形.
对于较长的技术文档（每篇包含数十个图和数十个表），请分别为图和表创建单独的清单。 如果空间允许，可将它们放在同一页上，如下图所示。 你可以在标题“List of Figures and Tables”下将两个清单合并，并像下图所示那样将条目标注为“图”或“表”。
介绍
任何技术文档的一个重要元素是其引言—确保你清楚它的真正目的和内容. 在技术文档中, 引言使读者为阅读技术文档的主体做好准备. 参见 介绍 关于写作引言的讨论。
请看这个介绍示例:
图表清单随后是引言。
如果没有表格, 就用 "图目录." 在技术写作课程中, 询问你的老师是否要求标题使用十进制编号
技术文档正文
技术文档的主体当然是技术文档的主要文本, 即介于引言和结论之间的各个章节. 下面展示的是示例页面.
标题
除非是最短的技术文档（两页或更少），在文档中使用标题来划分所涵盖的不同主题和子主题。标题使读者能够浏览你的技术文档，并在出现他们想要的信息的地方快速跳到相应部分。参见 标题 有关标题的指南.
项目符号和编号列表
在技术文档的正文中, 也应在适当的地方使用项目符号列表、编号列表和两栏列表. 列表有助于强调要点, 使信息更易于理解, 并打破密集的文字墙. 参见 列表 有关列表的指南.
符号, 数字, 和 缩写
技术讨论通常包含大量符号, 数字, 和缩写. 记住, 在技术领域中使用数字而不是用文字表示数字的规则有所不同. 关于把所有小于10的数字都写成文字的旧规则并不总是适用于技术文档. (参见 数字 与 单词 有关指南.)
除了技术文档的正文之外.
在技术写作课程中，询问你的授课老师是否要求标题采用十进制编号样式。另外，可能需要不同的文档系统—而不是 IEEE，后者是面向工程师的。
图形和图表标题
交叉引用
您可能需要将读者指向您技术文档中密切相关的信息，或指向其他具有相关信息的信息来源。 这些被称为 交叉引用 交叉引用.
结论
对于大多数技术文档, 你需要包含一个结尾部分. 当你规划技术文档的结尾部分时, 思考它相对于文档其余部分可以发挥的功能. 有关结尾部分的想法见 结论.
附录
附录是位于结论之后的那些额外部分。你在附录里放什么？—任何不太适合放在技术文档主体中但又无法被完全省略的
信息来源
文献引用系统因专业和领域而异。工程师使用 IEEE 系统，其示例贯穿本章。另一种常用的文献引用系统由美国心理学会 (APA) 提供。参见 文档 有关详情.
页面编号
传统技术文档设计中使用的页码样式与当代技术文档设计不同，主要在于前者在前置部分（即介绍之前的所有内容）使用小写罗马数字。
注意: 更长的技术文档通常使用称为按章页码或双重编号的页码样式（例如，第2章的页面将被编号为2-1, 2-2, 2-3, 等等）。类似地，表格和图表也会使用这种编号样式。该样式简化了添加和删除页面的过程。
用于技术文档的 AI 提示
通常未被阅读的清单, 经过一些修改后可以作为 AI 提示的来源. 复制以下内容, 将其粘贴到诸如 Google 的 Gemini 等 AI 系统中, 看看你可能遗漏了什么.
注：所有关于申请信的内容、格式、风格或其组成部分的参考均可在 在线 技术-写作 教科书.
|
用于技术文档的 AI 提示 当你想让 AI 评估一个写作项目时，先介绍你自己，告诉 AI 你是谁、你想要什么。给 AI 一个用于评估的参考点，比如一本在线教科书。然后发布你希望 Gemini 在评估中检查的内容。下面是一个示例： 你好，AI。我是David McMurrey，奥斯汀社区学院（奥斯汀，德克萨斯州）的一名网络安全学生。我请求您使用此来评估以下技术文档 在线教科书 和以下问题： |
相关信息
我将非常感激你对本章的想法、反应和批评: 你的回复—大卫 麦克默里.
