什么是好的技术文档
👓
1 ） 结论：
- 谁会读你的文档，为你文档的受众考虑，爱护他们，选择他们能懂的表达方式
- 思维要清晰，逻辑要简单
- 及时更新你的文档，为了读者不接收错误的信息，而努力维护好文档
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 后缀