标题
文档结构是技术文档的重要组成部分,一个良好的文档结构能有效帮助读者理解和掌握文档的逻辑和主题。以下是一些关于文档结构的关键要点。
层级
在技术文档中,我们通常使用的**标题层级最多不超过三级。**标题应该按照层级递增,禁止跳级使用。为了保持文档的整洁和一致,除非有特殊需要,否则不建议使用四级标题,可以选择使用列表代替四级标题。
描述
标题的描述应简洁明确,可以采用:名词词组、主题词 + 动词、动词 + 主题词、定语 + 主题词、介词 + 定语 + 主题词等形式。它们应能概括反映本章节的中心内容。为了保持标题的一致性,同级别的标题应尽量使用相同的结构。
- 名词词组: 例如「数据结构」、「网络安全」等。
- 主题词 + 动词: 这种形式更加动态,例如「电池充电」、「程序执行」等。
- 动词 + 主题词: 这种形式可以清晰地指示一个操作或行动,例如「安装软件」、「编写代码」等。
- 定语 + 主题词: 这种形式可以给出更多的描述性信息,例如「高效的算法」、「重要的更新」等。
- 介词 + 定语 + 主题词: 这种形式更加详细,例如「对数据结构的理解」、「在网络安全中的防御」等。
注意事项
- **避免重复:**例如,如果一级标题是「数据结构」,那么二级标题应避免再次使用「数据结构」,而应该是更具体的主题,如「数组」、「链表」等。
- 避免使用标点: 例如,不应该写成「数据结构:数组。」,而应该是「数据结构:数组」。
- 避免解释缩略语: 例如,不应该写成「API(Application Programming Interface)」,而应该在正文中解释这个缩略语。
- 添加引导性句子: 例如,在标题「数据结构」和「数组」之间,可以添加一句话:「接下来,我们将详细讨论数据结构中的一种重要类型——数组。」
- 避免孤立编号的标题: 正文不要有孤立的三级和四级标题,每个标题都应该在上一级标题的基础上展开。例如,如果一个部分只有一个三级标题,那么它应该被升级为二级标题。
- 项目列表作为最小编号单位: 不应在项目列表中嵌套任何级别的标题。例如,列表中的每一项都应该是一个完整的思想或概念,而不是一个需要进一步分解的主题。
段落
段落是正文部分的基本构成单元,由多个句子组成。**每个段落应只有一个主题或中心句子,并且中心句子建议放在段落的开头,对全段内容进行概述。段落长度建议在 50~250 字之间,避免超过 300 字。**为提高可读性,段落之间应设置适当的间距。同时,技术描述类主题应考虑先图表、后句子的原则,避免仅依赖段落陈述。
另外,**句子应避免过长,建议不超过 100 字。**使用简单句和并列句,避免复杂的复合句,可以适当地断句,防止句子过长。
示例
目录
文档目录是帮助读者快速浏览和定位章节的重要工具。通过各级标题,我们可以自动生成文档目录。例如,技术手册必须提供总目录,包含所有章节和附录。在网页端发布的技术手册,通常会有全手册导航栏和页内导航栏,相当于总目录和单篇文档目录。这需要根据使用的文档框架自定义文档的标题层级,以确保导航栏能正确显示。