《如何写作通用教程》将通用写作拆解成五个部分，总结了在写作前 、写作中 和写作后三个阶段需要注意的写作要点和技巧，通读整个系列文档，可以帮助你搭建系统的技术写作知识体系。
第一章: 何为极简
极简主义 （ Minimalism ） 概念在建筑、设计等领域有诸多应用。写作中的极简主义与其他领域的极简有些许不同。总的来说，极简写作有如下特征：
✓ 用 最精炼的语言 概括最 有价值 的 信息 Big ideas in a simple way
✘ 非单纯缩减文字，甚至"偷工减料"
写作中的极简主义简化的是 用户理解信息的成本。例如，多数用户不喜欢直接阅读用户手册，而是凭先验知识直接上手使用产品。先读手册、再用产品往往是违反用户习惯的。因此，极简写作要求我们尽量去除冗、去繁（如：长篇介绍、总结），最好提供能直接上手体验的真实案例。
极简主义有一套可供指导文档写作的方法论。例如，Every Page is Page One 的写作原则，即信息模块化、结构化，允许用户从任何顺序阅读，而不用为了了解当前页信息大量翻阅其他文档。
极简并非写作的终极目标。例如，给开发人员提供 API 文档时，我们仍需确保提供全面的信息，但可以用极简原则使之以更清晰、简洁的形式呈现。
第二章：为何极简
- 避免过度表达，节省读者精力 & 时间。
- 易于理解，便于快速定位所需内容。
- 更简洁的内容意味着更少的成本，如文档维护量、潜在的本地化或翻译成本等。
第三章：如何极简
在真实写作场景中，我们可以从多个方面来尝试简化写作。
保持一致
保持一致可以满足读者潜意识里对秩序感的需求，减少 认知负担。我们可以从保持人称、语气、字体、格式的一致下手。
动笔前，可以先问明确一些基本问题：怎么称呼读者？用什么代词和时态？以及何种写作风格（客观、正式、带有个人色彩的)？
💡 人称叙述
指代读者/用户时，我们一般用第二人称"你"；并且需要避免多个称谓指代同一个读者/用户。例如，可将"你"、"开发者"、"用户"统一称作"你"。
| Bad case | Good case |
|---|---|
| 在我 的账户中更改你的偏好设置。> 混用不同的人称代词会让读者感到困惑。 | 改写 1： 更改你账户的偏好设置。 如果"我的账户"是一个界面控件名称怎么办？ 改写 2： 点击 我的账户，更改偏好设置。 |
💡 语气语调
| Bad case | Good case |
|---|---|
| Uh oh! An error occurred, and we were unable to publish this post. - Uh oh：自然、随意 ------ 像小孩说话。 - An error occurred：技术写作风格 ------ 像语音机器人说话。 - we were unable to publish this post：语气礼貌但略消极（没有提供解决方案）------ 像一个礼貌却拒绝你要求的客服。 | Sorry, we couldn't publish your post because of a problem on our side. Try publishing again. 光道歉还不够。加上 Try publishing again 让用户点击跳转链接，尝试解决问题。 |
避免啰嗦
💡 避免过度使用行话/术语
- 不要用读者无法理解的术语；选用更直接的词。
- 行话是特定领域的术语，若受众不是特定领域的专家，建议使用日常用语。
| Bad case | Good case |
|---|---|
| 发生了认证错误。 | 你输入了错误的密码。 |
有时我们在营销话术中会过度使用行业术语，让它们演化成了一种"修辞手法"。如果我们想让内容脱颖而出，不妨试着 描述产品亮点，而不是滥用某些术语，如：
| 词汇 | 可能的改进方式 |
|---|---|
| 数字化转型 | 常用于描述巨大的现实影响。试着把重点放在转型的内容上，而不是滥用该词。 |
| 云迁移 | 没人喜欢搬家😭，无论是搬房子还是搬数据。该词本身并非"独家卖点..."，重点把它放在能给用户带来的益处上。 |
| 颠覆性创新 | 每家科技公司都宣称自己在颠覆和创新。除非解决方案确实具备颠覆性，否则，勿过度使用。 |
💡 戒掉英式中文
英式中文是结合了英文词汇或结构特点的中文。中文常用一个短句做主词；英文则常用一个抽象名词或名词词组，例如，「名气」写作「知名度」，「更有远见」写作「更具前瞻性」，都是西化了的中文。过度使用的结果是软化、架空了动词，逼得许多明确而有力动词渐渐变质，成为面无表情的词组。如：
| Bad case | Good case |
|---|---|
| - 本校的校友对社会作出了重大的贡献 。 - 昨晚的听众对访问教授作出了十分热烈的反应 。 - 我们对国际贸易的问题已经进行了详细的研究 。 - 心理学家在老鼠的身上进行试验 。 - 切勿像传统影片那样，来回快速地对镜头、场景位置进行直接切换。 | - 本校校友对社会贡献很大 。 - 昨晚的听众对访问教授反应十分热烈 。 - 我们已对国际贸易问题详加研究 。 - 心理学家用老鼠来做试验 （或：心理学家用老鼠试验 ）。 - 切勿像传统影片那样，来回快速地切换镜头、场景位置。 |
某些情况下，我们需要在输入的源语言（英文）基础上创作中文，这时我们可能会扭转不过来，写出"英式中文"。
| Bad case | Good case |
|---|---|
| 如果你的应用满足 以下条件之一或更多。> 能感觉到是把 "one or more of the following conditions" 直译过来了。 | 如果你的应用满足 以下一个或多个 条件。> 更符合中文的语序。 |
💡 删除非必要内容
大胆删去非必要内容；若信息是必需的，把它变为更清晰、简明的概念。
| 非必要词汇 | 更简单的词 |
|---|---|
| - 无实质意义的词 （删掉不会改变句意），如：有点儿、实际上 ... - 意义重叠的词 ，如：各种各样、各式各样、缺点和不足 、怎样才能... - 含义已被其他词涵盖的词 ，如：先进的的创新、没有经验的新手、最低的底线、单纯靠...也不是唯一的方式 - 多余的"的" | 用词代替短语 。如： - 在... 情况下 -> 如果 - 由于... 的原因 、鉴于这一事实 -> 因为 - 缺乏... 的能力 -> 不能 - 可能的例外情况是 -> 除了... 否定变肯定、主动代替被动、避免双重否定 |
💡 缩减长句&段落
尽量避免使用长句（英文中避免使用过长的从句），写节奏明快的短句。
| Bad case | Good case |
|---|---|
| 提供三个不同的函数：Alpha、Beta 和 Gamma。这些函数的返回值由输入决定。如果输入等于 GREEN，函数 Alpha 将返回 true， Beta 将返回 false，而 Gamma 返回 true。 如果给定的输入是 RED，那么函数 Beta 和 Gamma 都将返回 false， Alpha 返回 true. 上文看起来冗长无比，相信你也没有足够耐心读完。 | 改写 1: 列表 提供三个不同的函数：Alpha、Beta 和 Gamma。 若 输入 = GREEN，函数返回值如下： - Alpha: true - Beta: false - Gamma: true 若 输入 = RED，函数返回值如下： - Alpha: true - Beta: false - Gamma: false 改写 2: 表格 下表展示了函数输入如何影响返回值： 改为列表或表格，将信息分解成可消化的小块，就清晰简洁多了。 |
具象化表达
💡 量化表达
数字也有修辞功能，如提供上下文、让观点具体、让描述更准确。
| Bad case | Good case |
|---|---|
| - 几乎所有客户。 - 运行速度变快了很多。 - 第四季销售额明显上升。 | - 87% 的 Prime 会员。 - 服务端 tp90 的延迟从 10ms 降到了 1ms。 - 2011年第四季度单品销量同比上升 40%。 |
💡 擅用类比/比喻
| Bad case | Good case |
|---|---|
| API（Application Programming Interface,应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。 API 的百科释义，对于没有计算机背景的读者来说略显晦涩。 | API 类似于饭店服务员。服务员问你想吃什么，并让你把点菜写在一张纸上。写好后，你把单子交给服务员。过一会儿，服务员将菜端给你。这个服务员就是这个餐厅的 API。你不需要知道鱼是哪儿买的、如何烹饪，只需要联系这个服务员（API），把点菜写在纸上（给 API 一些数据）。服务员接单后，交给餐厅内部运作，再把菜端给你。 极简并不是字越少越好。此例运用了生活化的比喻，减少了缺乏计算机背景的读者理解信息的成本。 |
第四章：小结
是否极简、何时极简、如何极简需具体问题具体分析；若一开始就把极简当目的，那就错过了该过程中的重点：重要的并非精简的结果，而是能开始感知、思考两种表达间的差别。
本文除了分享思考，也希望鼓励大家保持觉知，不仅关注实用的"how"，更要保持对概念的反思、对"what"和"why"发问。
个体经验难免局限对事物的认知。希望和大家一同探讨对极简写作的理解。