# 关于技术写作的思考

我想通过书写这篇文章，来梳理在进行技术写作时应该注意的要点。

---

## Before you begin

### Have something to say

之所以要写作就是因为有话要说，想要把自己的观点传达给读者。如果脑袋里没有东西，是写不出好故事的。要先去调查，找到合适的材料。调查过程与写作过程是截然不同的思路。调查过程中接触的材料不一定会用在最终的文章写作中。

### Don't confuse wrting and learning

写作是很好的测试自己是否彻底理解某个主题的方式。谚语有云：

> 写作是上帝向你展示「自己的思想是多么地不完美」的方式。

如果脑袋里没有东西，说明对当前主题还不够了解，那么就需要进行学习。而学习需要时间和耐心。枯坐在电脑面前，拼命挤出一些句子，对自己没有帮助。通过阅读一本书、一篇博客或一篇论文来做更多关于这个话题的研究，并且做笔记可能是一个更好的时间投资。

### Know your audience

当我们更好地理解自己的受众，也就更容易将自己的想法传达给对方。预设受众的情况下，对于写作过程中的用词语气都会有所不同。

在写作时，可以尝试想象一个人，作为自己受众的代表。写作，就是直接和这个人进行对话。

### Respect your state-of-mind

state=of-mind 精神状态

写作需要长时间的专注。理想情况下，在写作开始时，就能够进入心流状态。在这一过程中，可以不休息地完成特定主题的写作。

准备写作就像准备远足一样，会很辛苦。在写作以前确保自己的精神状态良好。如果在自己疲惫的时候进行写作，不会有多大可能写出不错的文章。

然后，尽可能避免分心或远离会让自己分心的事情。让手机静音是很重要且有效的方法。找到适合自己的写作时间（2h或3h或一个下午），以及写作时间点（一个星期写几次、星期几写作）。

### Work the iron while it's hot

趁热打铁

就像编程，写作需要在短期内记住大量内容。我们需要回想起关于这个写作主题的很多细节。所有这些内容需要时间记忆，并且容易因为分心或者切换上下文而丢失。

如果脑袋里的内容足够写出一个主题的文章，那么留出写作时间，充分利用这些还存在于大脑中的内容。

### Heat the iron before working it

如果脑袋里没有那么多内容，有两种选择：一是不要写作，二是开始学习、将上下文载入大脑。

缺乏上下文是痛苦和拖延的常见根源。不要想着去完成这样一个 TODO：“写会议演讲”。完成这样一个 TODO 需要很多准备知识。

好的补充上下文的方式：

1. 浏览关于写作主题的笔记；
2. 和同事、陌生人或家庭成员讨论这个主题；
3. 阅读相关主题的书籍、博客或论文。

坏的方式：读 HackerNews 或看 YouTube。

## While writing

### Start at the Top not the Beginning

对于那些超过一页的文章，可以采取从上到下的方式写作，准备好一个大纲。一个大纲的大概内容：一个列表以及粗略的笔记。参考资料 Writing for Engineers 的[第一版大纲](https://github.com/HeinrichHartmann/HeinrichHartmann.github.io/commit/46be4c95faeda16996baf6799eca8a551b282565)。

分区的标题不仅仅是分割文章，而且是整个文章的总结。

### Fix the story-line before fleshing things out

大纲是写文章的第一步。它应该表明文章的主要观点。

### Finish the content before starting to polish

一些相邻的任务会分散我们写作的注意力，让自己以为这些事情才是重要的。这些任务包括：

1. 编辑：改错别字、整理段落结构；
2. 发布：调试网络发布流程；
3. 制作配图。

**记住：写文章的第一个里程碑是大纲。任何与大纲无关的内容都是会让我们分心。**

当大纲写完后，第二个里程碑是将大纲中的笔记，扩充为完整的内容。文章内容只需要涵盖笔记就行，不需要字句雕琢、写得很好。

当我们达到这一步时，可以开始打磨字句了：移除错别字、改善字词、调整段落结构。还有文章的配图。

### Make your text skimable

> 八秒。网站读者大概能持续八秒。
>
> ——[Winning the Fight Against a Website User’s Attention Span](https://www.towermarketing.net/blog/winning-the-fight-against-a-website-users-attention-span/)

用八秒的时间，向读者展示自己这篇文章的价值。在子标题中将文章的主要内容展示出来，以便读者判断文章是否满足自己的需要。

### Provide Summary Sections

为文章提供一个类似于论文的摘要。

两种：Abstract / Executive Summary / TL;DR 和 Conclusion。

要注意：这些摘要是独立于文章主题的，因此可以独立准备。写完文章主体后，再开始写摘要和结论，这样能更好总结文章。

## The Practice of Writing

### Keep Writing

> Developing a writing muscle, and writing relatively short medium quality documents every week will make you a much better writer than crafting highly polished documents once a year.

### Leverage small writing tasks as exercise

### Get early feedback on your outline

### Circulate drafts of the text to the selected audience

参考资料

- [Writing for Engineers](https://www.heinrichhartmann.com/posts/writing/)
- [How to Write More Clearly, Think More Clearly, and Learn Complex Material More Easily - WriteThinkLearn.pdf](https://www.covingtoninnovations.com/mc/WriteThinkLearn.pdf)
- [Writing, Briefly](http://www.paulgraham.com/writing44.html)
- [Technical Writing for Developers | CSS-Tricks](https://css-tricks.com/technical-writing-for-developers/)
- [Watch Me Make Mistakes](https://byronm.com/13sentences.html) 有趣的写作录制