文档写作四法则¶

技术文档种类繁多，各行各业对技术文档的写作要求也各不相同，但是有一些基本的写作法则可以适用于所有类型的技术文档，文档写作四法则分别是：

主题明确单一¶

明确是目的，单一是方法。在一个章节或段落中只写一个主题，在一个句子中只写一个主题字（关键字），在一个步骤中只写一个动作（动词或命令），让读者准确快速地理解所写信息。

主题明确单一还可以使读者快速的跳过不需要的信息，另一个好处是可以重复利用信息，更方便的组织（交叉引用）文档。

提示

技术文档切记堆砌内容，不要把各方面的知识都罗列出来，技术文档不是科普文章。

自己不理解的不要写，写出来也别指望让别人能理解。等理解后在写入文档。

语言简洁明了是写技术文档最基本的要求，语言要做到言简意赅，表述清晰，不能模棱两可。避免使用过长的句子，建议长度不要超过 100 字。

语言简洁明了对于翻译文档时也有好处，可以降低语言转换时的难度，避免信息失真或缺失。

俗话说：文不如表、表不如图。大段的文字描述和图表相比，图和表的条理性更清晰、表现更生动、形式更吸引眼球，更易于阅读和理解。

表不只是指表格，网页中的无序列表和有序列表也属于表的一种。图包含很多种形式，例如：思维导图、电路图、逻辑推到图、GIF 动画图等等，视频也属于图的一种。

提示

在写技术文档时，当使用 300 字描述不清一个主题时，应该考虑用图表的形式描述内容。

多举例会能让读者更容易理解文档所描述的内容。例子可以使所要说明的内容具体化，好例子的作用能超过正文。

好的举例要注意以下两点。

举的例子一定要是典型的、有代表性的，能够让读者通过例子清晰准确地了解所要表达的完整含义。

举例的目的还是为了让读者理解正文的内容，不能直接以例子来代替正文。