技术文档怎么写

1. Preparation 准备阶段

准备阶段的工作主要包括以下几点：

·明确文档需求

·明确文档受众

·界定文档范围

在写文档之前，需要明确文档需求。你要了解为什么要写这篇文档，写这篇文档是为了达到什么目的。

也要明确文档受众。受众不同，内容就很可能不同。比如，面向开发人员和非开发人员/普通用户的文档，在内容的组织上就会不同。

还要界定文档范围。思考并确定这篇文档需要覆盖哪些内容或模块，以及不会涉及哪些内容。这样在之后搜集资料的时候就会有所侧重，写的时候也不会模糊不定。

相关推荐：《php入门教程》

2. Research 调研阶段

有过技术文档写作经历的小伙伴一定会深有同感，如果不理解某个东西，那么给它写文档简直太痛苦。

那么当遇到一个让你毫无头绪的陌生主题时，该如何尽量避免这种痛苦呢？当然就是尽最大可能去理解了。

可是具体该如何做呢？简言之，即搜集资料。那又该如何搜集资料呢？笔者认为，可以从以下几点着手：

（1）对比较有代表性的同类产品或相似产品的相关文档进行调研，看看别人的文档是怎么做的。

在一无所知的时候，借鉴他人的经验做法不失为一种好的选择。通过对几家产品的文档进行对比，你就可以对自己要写的文档建立一个大致的框架。

需要注意的是，借鉴不是照搬，只用于提供思路；产品不同，文档的结构规划也会有差异。

（2）采用最有效的方法尽力搜集与所写文档相关的各种资料。

搜集的资料经过 Technical Writer 的摘删组织，很可能就会成为发布文档的一部分。

搜集资料的方法有很多，像网络搜索、调查问卷、访谈、实验，以及邮件讨论、报告、技术文章等等。到底该使用哪种方法要具体分析，需要你根据文档需求、Deadline、已有资料的丰富程度等因素，来选择能快速而准确地搜集到所需资料的方法。

有些主题的写作，通过网络搜索可能几乎无法给你提供任何帮助。即便是这类内容，你也可以从开发人员那里获得一些资料，可以根据自己的需求请他们协助提供资料，抑或是通过内部系统中的开发说明和讨论获取所需信息。

对于软件类的产品文档，即便有了一些技术资料，也往往需要 Technical Writer 自己使用一遍，从而对操作步骤有一个直观的理解，获得文档写作的一手资料。

3. Organization 文档架构

当资料搜集得差不多的时候就可以组织这篇文档的具体结构了，之前对相似产品的调研或许可以在此时助你一臂之力。

对于常见的产品使用指南，一般按照安装或使用的顺序进行组织；对于其它一些非指南类的文档，也应遵循一定的顺序或逻辑。

此外，还需考虑该文档是否需要配图，是否需要使用表格。如果需要配图，明确是需要他人协助提供，还是需要自己完成。画一个较复杂的图也是一件蛮耗时的事情，花费的时间也需考虑在内。

有了详细的文档架构之后，就可以进行下一步的写作了。

4. Writing 文档写作

如果做好了前几步的工作，写作将变得非常简单，你只需把相应的内容准确地填到文档架构中。在这个过程中，你需要写一个个段落或者具体的操作步骤。这是一个反映你的语言和写作功底的时刻。

有的 Technical Writing 书籍中说到，在写文档的时候不必在意语法、措辞和标点，认为这些细节应该在 Revision 阶段完善。

Expand your outline into paragraphs, without worrying about grammar, refinements of language usage, or 
punctuation. 
Writing and revising are different activities; refinements come with revision. - Handbook of Technical 
Writing

我对此有不同的看法。一个合格的 Technical Writer 本身应该有良好的语言功底，像语法、措辞和标点这种最基础的细节本就不该成为一个需要单独解决的问题。规范的语法、得体的措辞、正确的标点应该已经成为一种不需要额外付出精力、也几乎不会占用额外时间的写作习惯。

如果写作的初稿比较粗糙，有许多需要修改的小细节，这必定会增大 review 时的工作量和时间成本，从而延缓文档流程。

或许，对于有精细化分工、每个人只负责一个小环节的大企业，可以采用这种方法。但是，对于快速发展、需要文档敏捷开发的创业公司，这种就不适用了。

5. Revision 审阅修改

写完文档第一稿后，一般都需要进一步修改完善。这里的 Revision 指的是 review 之后的修改，所以这一步也可以叫作：Review & Revision。

那么需要谁来 review 呢？技术文档通常需要请其他小伙伴进行两种 review，即：

·Technical Review：从技术层面看文档中的描述是否正确有效

·Language Review：从语言层面看文档中的表达是否简洁得体

收到 reviewer 的反馈之后，Technical Writer 需要及时作出判断和修改，有不明确的地方需和 reviewer 讨论确定。改完之后，再请 reviewer 看一下。如果又发现了新的问题，那么还需要再次修改。这个 review - revise 的过程可能会反复几次，很正常。

当然，在请他人 review 之前，Technical Writer 也可以先自己 review 一遍，尽量避免低级错误，不浪费他人的时间。

哈哈，问题又来了~通常，刚写完一篇文章的人是很不情愿再去看自己写的东西的，此时就可以使用一些语法拼写检查的小工具来协助你了。

如果你觉得自己足够细心，根本不需要小工具来协助你，我佩服你的能力，但还是建议用一下小工具。因为，你可能也会有状态不好的时候，有疲劳打盹的时候，有不知道自己写了一堆什么鬼东西的时候……不要跟自己和小工具过不去。

6. Delivery 文档交付

等文档定稿之后，就可以在平台上发布了，一般很容易操作。不同的公司的文档发布平台也会不一样，Technical Writer 使用的写作工具也不一样。

文档发布之后，并不代表着结束。根据我的工作经历，即便是已经发布的文档，也依然有可能存在问题，无论是大公司还是小公司的文档。例如：未发现的文字错误、失效的链接、与最新的产品已不匹配的描述和步骤等。Technical Writer 需要及时跟进产品动态，以便及时更新文档。

以上是技术文档怎么写的详细内容。更多信息请关注PHP中文网其他相关文章！