如何编写技术型文档和帮助手册

最近看了一些应用软件的官网的手册、文档，发现这里面确实存在不少需要注意和思考的地方。

读者、用户的几种形态：

1. 用户什么都不知道，但我要上手 → 需要快速入门指南
2. 用户知道大概，但忘了具体怎么操作 → 需要参考手册
3. 用户遇到了问题 → 需要故障排查/FAQ

文档的组织方式、目录结构、内容都有很多需要注意的地方，但总的来说，目的大概离不开这几点：

1. 让用户容易搜索到、找到有用的、需要的信息；

2. 尽量让用户能快速看明白，没有额外的思考负担；

3. 按照文档能够解决用户遇到问题；

4. 能让用户第一时间找到对应的文档；

5. 文档的编排、页面需要美观、简单直观；

6. 文档必须是有价值的配套，是深入和细致的解释说明，需要给用户解释清楚必要的概念、功能、有什么用、怎么用；

发现的一些存在的问题：

1. 有的产品的文档不容易第一时间找到入口，或者入口的进入路径比较深，有的文档的路径变来变去，本来已经收藏了后面却访问不到了；

2. 文档里含有太多的隐性假设，编写文档的人可能被知识诅咒了，错误的以为用户已经知道或理解了，但用户可能因为缺乏某些背景而无法完全理解文档的内容；

3. 文档里含有较多的错误（有逻辑错误、拼写错误等），文档上下文无法对接或者对接困难；

4. 文档没有很好地组织内容，缺少必要的清单信息、背景信息等，例如写一个部署文档，却没有给出所需的资源清单、先决条件、配置等；

5. 文档中某个软件写死固定的版本号或者标识符，导致存在依赖问题或者不是最新的版本；

6. 文档的排版错乱、没有适当的空行或者空行过多，内容之间过于紧凑或者存在割裂感；

7. 部分软件产品是多平台多架构的，文档只写了一种或者两种，对其他的平台或者架构没有写清楚或者干脆没有；

8. 文档不够完善，缺少某些环境依赖、后续步骤、回滚方案，没有讲清楚为什么这样设计，为什么这样做等；

9. 解决文档的文档只写解决方案，没有写原因或者写得模糊、笼统；

10. 只有文字，没有图、表等；

对文档编写人的一些要求：

1. 审美、严谨、标准化；

2. 站在用户角度的思考问题；

3. 学习他人，取长补短，取精华去糟粕；

4. 要有审核，审核要严格严谨，例如真实的照做，看看是不是按照文档能做到期望的结果，而不是仅仅看看有没有排版问题或者拼写错误等；

5. 好的标题、一句话摘要、创建时间、修改时间、文档有效期限、作用域等；

--