技术文档应该如何编写

# 衡量技术文档好坏的标准是什么

clipboard.png

Martin(Bob大叔)曾在《代码整洁之道》一书打趣地说：当你的代码在做 Code Review 时，审查者要是愤怒地吼道：

“What the fuck is this shit?”
“Dude, What the fuck！”

等言辞激烈的词语时，那说明你写的代码是 Bad Code，如果审查者只是漫不经心的吐出几个

“What the fuck?”，

clipboard.png

那说明你写的是 Good Code。衡量代码质量的唯一标准就是每分钟骂出“WTF” 的频率。

衡量文档的标准也是如此。

# 文档编写的要点

切记，编写文档的目的是为了让读者可以快速有效地获取他想知道的信息。

1. 要简单、清晰、明了。不要为了凑字数而堆字数。
2. 明确文档面向的读者和受众。根据所编写的文档，判断主要面向的受众是产品、技术、测试还是商务人员，尽量使用他们所能理解和熟悉的词汇和表达方式来表达。
3. 提供必要的信息。根据需要编写的技术类型，提供必要的信息，就像摄影拍照一样，有一些约定的摄影构图，例如：均衡式构图、对称式构图、对角线构图、三角形构图、九宫格构图等。文档也是一样，不同文档需要包含的元素、标题和部分也有所不同。然后当你熟悉 后，可灵活安排文档的内容，以最为恰当的结构形式来表达。
4. 排版与图片。尽量不要一味地只提供文字信息，这样会让读者看起来很压抑而且觉得是“天书”。应该适当留一些空行，让读者眼睛“休息”下，对读者友好一些。同时，提供一些代码片段、UML图片或相关的插图用于辅助说明。补充一些参考的文献和资料。排版上，进行分段，分章节部分，注意对重要的信息高亮、加粗、或重复说明。
5. 万事开头难。很多技术人员觉得编写文档比写代码还要难，还要头疼。其实写文档和写代码是类似的，很难一开始就写出完美的文档。应该是像写代码一样，一开始写得很丑陋，但没关系，至少有内容了。然后，可以不断重构文档，对缺少的信息补全，对多余的信息进行删除。最后觉得内容上OK的话，就可以再进行排版和修饰，补充一些图片。慢慢的，在通过用心花时间后，你的完美文档就慢慢出来了。
6. 责任心。及时更新，准确性，向后兼容。

# 参考资料

• 如何写好技术文档? (opens new window)
• 程序员如何编写高大上且实用的技术文档 (opens new window)