如何撰写技术文档

本文最后更新于2022年04月30日，阅读时请注意时效。

围绕“高效精准解决问题”简单介绍一下撰写技术文档的一些注意事项。

明确写作目的

想清楚要写的是什么：

• 是面向新手的详细的step-by-step guide吗？

• 是进行初级教学的tutorial吗？

• 是针对某个具体案例的solution吗？

• 是尽量全面的reference吗？

• 是用来备忘的笔记吗？

有了明确的目的之后，下笔的脉络就会变得清晰。

明确目标读者

想清楚写给谁看。如果是一篇面向新手的指导，那么其中的高级话题就可以不做展开；而在面向经验用户的文档中，一些基础知识就可以适当省略。相反，如果一篇讲解高级话题的文档对过于基础的知识进行了太多说明，文章就会变得冗长，读者也会难以从中高效的获取信息。

对读者水平的一些基础假设，可以参考阅读技术文档需要具备的能力。

突出重点

在前两点的基础上，将篇幅大量分给文章解决的独特的问题上。对于很容易就能搜索到的内容可以一笔带过。提醒自己不要把技术文档写成wiki。这一条可以节约大量时间。

注明出处/理由

注明出处/理由可以让一篇文章看起来像是有据可循技术文档而不是某种神秘而不可告人的魔法，这些信息往往可以帮助读者弄清楚文中的解决方案是否适合自己。

另外，被问题卡住的新手很多时候是因为找不到好的信息源，通过注明官方文档的位置/推荐一个好的论坛的方式往往可以让读者获得更多文章以外的开阔视野的机会，也可以帮助读者养成更好的思考方式。

放上截图、日志、代码片段

提醒自己，即使是自认为“客观的描述”也十分容易失真、让人困惑。在关键位置放上“原文”，这样即使在描述上存在理解的差异，读者也可以根据这些信息复现文中的实验。

尽量使用文本

文本的通用性很强，文本的阅读速度很快，文本方便搜索。

保证明确的情况下尽量短一点

读者的时间很宝贵，作者的时间也很宝贵，少些一点可以节约时间，参照unix “do one thing well” 的哲学，一篇重点突出的小文已经够用了。

引用：

the art of unix programming - page 12: "Make each program do one thing well."