• 谁会读你的文档，为你文档的受众考虑，爱护他们，选择他们能懂的表达方式
• 思维要清晰，逻辑要简单
• 及时更新你的文档，为了读者不接收错误的信息，而努力维护好文档

2 ） 正文：

我经历的公司之一

很强调文档的建立

因为很多知识在员工的脑子里

准确的说，是前员工的脑子里

于是

当员工离开后

面对注释不多的代码

就要建立文档

各种构建说明，问题解决的问题

2.1 )

我之前会在自己私人项目的代码里

写一些自己的注释

很不规范，甚至啰嗦，甚至带有情绪（惊奇，疲倦，沮丧，生气）

但是我能懂我当时写注释的情景

理解我的困惑

标记代码线路

我的 git （一个代码版本管理软件） 提交 消息，也是很口语的

甚至带有无关故事和情绪的 提交 消息

这会让某些技术人员反感

2.2 )

不过有的公司要求“代码即注释”

也就是少写注释

因为担心注释赶不上代码的变化

这或许是有道理的

听说大公司华为就是这样的要求

于是，在那样的公司里，我不怎么写文档和注释

2.3 )

总之回到文档这一个话题

什么是好的文档呢

我觉得是让别人和自己都懂的文档就是好的文档

形式不那么重要

用pdf，word，markdown，用xx云笔记，typora，latex 都行

但是我想

最好的就是 txt

纯文本的威力是巨大的

你自己敲的每个字，是威力巨大的

文档模板看起来很重要

它规范的大家的思考路线

但是面对未知的时候，人们无法使用模板

而是只能打草稿

分析草稿上的信息

最后完成思维的演算

才能按照模板进行文档编写

可贵的是思考的过程

于是

草稿对我来说是重要的

它保留了你思考的轨迹细节

尽管你会走弯路

2.4 )

模板是站在楼顶的人的产物，而文档的阅读者，很有可能在第一层

我读到下面一段话：

“你不能自己站在11层上，然后假设你的读者站在第10层，指望着只要告诉他第11层有那些内容就让他明白。你的读者站在第一层，你必须知道你脚下踩着的另外10层到底是怎么构造的。这就迫使你对你所掌握的、或之前认为正确的那些东西作彻彻底底的、深刻的反思，你的受众越是不懂，你需要反思得就越深刻”

摘录来自 暗时间 刘未鹏

2.5 )

硕士期间，我和同学们会写论文

而论文是有标准模板的

第一章节 就是 介绍背景， introduction 部分

第二章 就是 方法， Method

然后 实验 ， experienment

最后 结论，展望啥的。 conclusion

本科期间

我讨厌论文

我对同学说：论文，就是不说人话

终究，我还是不说人话，才能硕士毕业呀

2.6 )

但是，我还是不爱看论文

我的偏见是：

论文是可恶的

科普的文章是好的

上面的红头文件是可恶的（官腔）

乡民自发的约定是好的（大白话）

所以暂时我的想法是

好的技术文档就是大白话

就是朗朗上口的口语表达

不要用太多术语

显得你很专业

2.7 ))

然后一个文档要小

围绕一个问题就好

不要大而全

一句话能说明问题

一句话能说明结论

不要堆切辞藻

不要过分在意 格式，图示的标题，左右对齐还是居中

2.8 )

你要在意的是：

• 谁会读你的文档，为你文档的受众考虑，爱护他们，选择他们能懂的表达方式
• 思维要清晰，逻辑要简单
• 及时更新你的文档，为了读者不接收错误的信息，而努力维护好文档

这3点 就是我理解的 好的 技术文档的 标准；

---

附件实际上是 WindTerm_2.7.0_Mac_Portable_x86_64.dmg + 了 txt 后缀