优秀文档编辑技巧
优秀文档编辑技巧
总述
- 想清楚，再下笔
- 多从「用户视角」出发
- 用好的「结构」让读者理解你的思路
- 选择合适的「呈现形式」，突出重点
- 保持「精简」
- 清晰的表达
- 「细节」决定成败
- 保持输入，不断「迭代」
写个人博客，已经有近一个月了。以做技术记录出发，「面向小黄鸭编程」的方式,确实更容易坚持下来，做起来也更有成就感。但是，总是感觉自身的写作还不是很好，为此，总结一下「字节跳动优秀文档」的编辑技巧(原文档链接见参考文档)。
动手前，先「想清楚」
- 写作前，我们应当先自己脑中过一遍，思考逻辑是否自洽、准备工作是否有做足。
这其实很重要，就如个人博客，笔者刚开始时，不大喜欢用图床，觉得较为麻烦。如有必要使用，便选用已有的图床。但是，随着写作的深入，发现这其实是不可持续的，你必须要有自己的图床体系，或者缓存在博客网站中。为此，你还是得学习像 PicGO等软件方法。其实也不算麻烦，能够加快编辑的速度。
- 除逻辑是否自洽外，还需要想清楚是否能够将这件事情讲清楚，是否他人能够读懂。
如果不能将事情表述清楚，如果没能捋顺，说明还没想好，这是大忌。（反应到自身，好像很多都是这样，得改！）
多从「用户视角」出发
应当将文档当做「产品」一样打造，转变自身的视角，以用户的角度进行查看：
我的沟通目标是什么？ 以写一份「产品需求文档」举例，沟通目标就是「评审一次过」！那么文档里写的内容，能不能帮助我达到目标？
我的「用户」都是谁？
结合文档的使用场景去看，例如一份双月汇报材料，读者往往包括管理者+协作者+信息同步对象；
Ta知道什么?需要假想你的「用户」所掌握的信息
Ta想知道什么?假想如果只让对方提 3 个问题，那么对方会问什么？
以上这些，其实是很难的，但是收获其实是很大的。张鑫旭老师就曾说过，自己的博客之所以受欢迎，有很大一部分原因是自己会回读自己写的东西是否能让别人看懂。过于生涩的内容就反复修改，久而久之就形成习惯了。这也是一件很厉害的事。
用好的「结构」让读者理解你的思路
就像高考议论文一样，文章的结构应该为：虎头、猪肚和豹尾。写作博客文档也是一样的。
- 虎头：以精炼的语言概括全文。将背景、要解决什么问题、建议方案精简地总结在开头，让读者快速浏览后心里产生一个问号 ❓，紧接着我们再用正文解答读者的疑问；
- 猪肚：也就是正文部分，像金字塔形一样的每个章节按照「总-分」或者「总-分-总」的形式进行写作。
- 豹尾：结论是起到总结的作用，以「敲黑板划重点」的方式加强读者对问题的理解，同时明确下一阶段的行动。
选择合适的「呈现形式」，突出重点
在表现形式上，纯文字肯定是枯燥乏味的，可以借助其它形式：
借助图表：
- 涉及到大量数据的，选择表格比打一堆文字更一目了然；
- 此外，还有甘特图(条状图的一种)、脑图、泳道图(一种 UML 活动图)等不同的图形化表达方式，可以结合内容针对性选择；
通过加粗 / 标记颜色 / 斜体等方式高亮重点信息
- 高亮内容适用于总结句或关键数据，建议大家克制使用，否则会模糊真正的重点
但是，本人还是喜欢多文字的表现。（o´ ﾟ □ ﾟ`o）
保持「精简」
个人的精力是有限的，虽然上文中说到要假设你的读者知道什么，但是也切不可假设读者什么都不知道。否则信息将过量，呈现形式也不会很友好。
精简，就意味着要多总结。归纳会减少人的记忆成本。
多用「面向小黄鸭编程」的形式进行写作。如果一部分内容感觉不大需要，就问问自己，如果去掉这部分，会不会出现明显的减损？如果答案不是肯定的，那就可以去掉。
清晰的表达
清晰的表达，也就是说人话。高大上的词汇很容易劝退他人。如上文中的「甘特图」，虽然我们都用过条状图，但是如果不是专门做过报表，那么一般读者理应是不知道这种词汇的。所以，我们应当给出注释，以便理解。
「细节」决定成败
检查的内容应当包括：
- 格式检查：并列呈现的信息要对齐，否则你的“房子”看起来会歪歪扭扭；
- **错字等细节检查：**错别字、大小写、全角/半角标点、单位保持统一、数字小数点等等。
保持输入，不断「迭代」
技术是会更新的，随着自身对于技术的理解逐渐增加，可以适当对以前的博文进行迭代。这是保证质量的关键，同时，也能巩固自身对于技术的理解。
软件手册目录结构
软件手册是一部完整的书，建议采用下面的结构。
简介（Introduction）：[必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
快速上手（Getting Started）：[可选] [文件] 如何最快速地使用产品
入门篇
（Basics）：[必备] [目录] 又称“使用篇”，提供初级的使用教程
- 环境准备（Prerequisite）：[必备] [文件] 软件使用需要满足的前置条件
- 安装（Installation）：[可选] [文件] 软件的安装方法
- 设置（Configuration）：[必备] [文件] 软件的设置
进阶篇（Advanced)：[可选] [目录] 又称“开发篇”，提供中高级的开发教程
API（Reference）：[可选] [目录|文件] 软件 API 的逐一介绍
FAQ：[可选] [文件] 常见问题解答
附录
（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
- Glossary：[可选] [文件] 名词解释
- Recipes：[可选] [文件] 最佳实践
- Troubleshooting：[可选] [文件] 故障处理
- ChangeLog：[可选] [文件] 版本说明
- Feedback：[可选] [文件] 反馈方式