1. 问题描述

技术写作是为了总结解决问题的实用技术，而撰写的文档，对团队的技术积累非常关键。

为了准确、高效的传递技术价值，技术文档写作方法必须满足两个条件：

• 清晰、条理化；
• 快速；

第一点很容易理解，第二点在实际中更关键。如果不能快速写作，那么新鲜的思考成果会迅速流失，淹没于各种杂事之中。

针对以上两个问题，本文总结了一套标准的技术写作模板。

2. 技术背景

清晰快速的写作，需要借助一定的技术工具：

• markdown
• 网络

markdown是当前最高效的技术写作方式，图片的插入需要在网络条件下使用。如果不使用markdown，而使用word，未尝不可，但效率会低很多。

关于markdown可以关注本人的其他文章，或直接百度。

3. 解决方案

一个基本事实是：填空题比简答题容易做。与之相对应，设计一套标准的技术文档模板，将一个创作的问题转化为填空问题，只需要参照模板，填入需要的信息，不需要思考文章的结构，那么写作过程自然大大提高了。

以下介绍技术文档写作的主体结构和附属结构。一般非正式的文档只需要主体结构即可，但对于更复杂的问题，或者面对更大的阅读者群体，最好补充适当的附属结构信息。

3.1 主体结构

• 问题描述
  这是一个什么问题，在什么样的情境下出现。以便读者对号入座。
• 技术背景
  介绍基本的背景：原理方法概述、软件说明。
  经历允许的情况下，尽可能做到知其然，知其所以然，这样的文档更有生命力。
• 解决方案
  总体描述，解决问题的思路、方法、以及技术要点。给出大轮廓。
• 实施示例
  选取代表性的案例，分条描述实施过程，让技术工作可重现。
• 常见问题
  补充简述需要注意的问题。

3.2 附属结构

附属结构是锦上添花：

• 标签分类；
  这是知识管理的问题，此处不展开叙述。文档数量较多之后，必须解决这一问题；
• 目录；
• 参考文献；
  便于读者顺藤摸瓜，了解其他相关信息；

4. 实施示例

一个典型的标准化技术文档写作示例如下：

标题与目录 正文-1 正文-2

5. 常见问题

技术写作的最大问题在于追求完美。苛求完美的结果往往是——写不出来。
时间表明，昨晚工作后，及时用10 min时间回顾总结几个基本步骤，截取关键图片，写一篇不完善的文档，也是很重要的积累。积累比完美更重要。

如果写作太慢，用1个小时的时间总结半个小时的工作，那就得不偿失了。

本文用时：30 min。