如何写好一篇技术笔记

翻看前些年的技术笔记，发现内容的详尽程度，将决定未来能留下来多少知识。不论记性多好，大多数内容都会随着时间遗忘在历史的长河中。

技术笔记和其他类型的笔记不同，详尽程度将决定笔记的质量。

一些十多年前的笔记我现在已经完全看不懂了，有的文档仅仅写了短短几句，明显没有写完，但真的就再也想不起任何内容。

痛定思痛后，我决定写一篇如何写技术笔记的文章。

1/ 技术记笔记的要求

在技术笔记中记录详细的信息，是为了在若干年后，可以重现所有的操作。如果笔记内容的上下文有丢失，后期将无法利用笔记指导自己工作。

反复学习，不断迭代，所有的积累才能有效累加。为了达到这个目的，写技术笔记至少需要做到以下几点：

• 完整性：必须包括原始需求、先验知识、现有解决方案、具体实践、参考文献。
  • 具体实践包括不但包括成功的经验还包括失败的尝试
• 严谨性：所有笔记内容都经过验证，包括参考文献中的结论，没有验证过的就说未验证。
• 可复现：完整展示环境搭建过程，命令行的所有参数，完整的命令行输出，完整的源代码和编译参数。
• 深入细节：魔鬼都在细节之中。笔记详细说明各种坑点，关键细节的细微差异。
  • 刨根问底，使用调试器等工具展示底层的细节。
• 持续性：反复迭代，在自己感兴趣领域的不断积累。

失败的尝试是最容易忽略的地方，明明查询了很多资料，尝试了很多不同的方法，最后记录的只有成功的那个方法。

在极端的情况下，所有的尝试都失败了，是不是就完全放弃了？如果记录了失败的尝试，当你重新尝试解决问题时，你不会重复走上次失败的路径，否则，你大概率还会重复走某条失败的路径。

2/ 笔记中目录和时间的作用

以上是一篇过得去的技术笔记的基本要求，更好的技术笔记需要一个详细的目录。

文档的目录是内容的索引，在篇幅较长的笔记中，可以快速定位到你关注的内容所在位置。使用 markdown 写技术文档很容易做到这一点，只需要根据内容划分好章节，利用 Headings 做好标记即可。

在 markdown 中，可以使用 ## ### 等表示目录的层级

文档的目录，是一篇文档内容的提要，也是一个大纲。 考察目录，很容易发现笔记中缺失的内容，写出的笔记在结构上更加完整。

我写笔记时，在文档编辑器的侧边栏，展示文档的大纲目录，可以实时观察文档结构的变化。

同时，目录还可以增加笔记内容的条理性，按照最简单的思路平铺直叙地记录。

阮一峰，在 《技术写作的首要诀窍》中也提过这个要点：「技术写作的首要诀窍是什么。很简单，就是一句话：文章采用单线结构。」

在技术笔记中，记录文档创建时间和修改时间，是另外一个容易被忽视的地方。

一篇古老的技术笔记所能发挥的作用，可能是极其有限的。在 Python 2.7 上的技巧性写法，在 Python 3 中大概率会出错。

同一个技术问题，在不同的时期也可能会有不同的解法。

可以参考这篇文章：如何用GDB调试子进程 https://scz.617.cn/unix/201206011217.txt

3/ 参考资料的学问

我以前写参考资料时，只有一个链接地址，总是觉得这样就足够了。后面觉得应该要写个标题，这样可以一眼看出参考资料的主题。

但如果只记录参考资料的链接和标题，其实是存在信息缺失的。

从技术演进的角度看，文章发表的时间是非常有意义的，从总体上看技术是进步的，我们应该优先学习先进的方法。

作者信息则可以让我们认识领域的专家，靠谱作者写的文章，可信度应该上调一个级别。

scz 在微博上举例，利用参考资料的时间信息构造网页链接例子：

有些十多年前的微软blog，可能形如:

h__p://blogs.technet.com/b/<part0>/archive/<year>/<month>/<day>/<part1>.aspx
原链接肯定不存在了，其中一部分可以换成下面这种样子去访问

h__ps://learn.microsoft.com/en-us/archive/blogs/<part0>/<part1>

所以，参考资料应该记录：标题、作者、日期、链接

4/ 严谨的记录带来一种有序

严谨的记录是对内心的一种拷问，要求不断地问自己是否真搞清楚了，有没有遗漏前提条件，是否只是某种巧合。

严谨的记录带来一种新的有序，不断完善的基础概念，不断增加的各种尝试/方法，从而提供跨出知识边界，跳出思维定势的可能性。

5/ 记笔记的态度比笔记方法重要

笔记是一笔可以积累的财富，认真写笔记可以在未来的时间里获得复利，态度决定一切，这比所谓第二大脑，卡片笔记法都重要。

任何可以持续积累并获得进步的习惯应该坚持下去。对于个人成长来说，不断记录，不断总结，不断分析，才能螺旋前进。

6/ 最后

以 scz 的话结尾：

若自己写的技术文档三个月之后乃至更长时间跨度，不能指导自己的相关工作，该文档严重不合格。该标准很靠谱，诸君可自行检验。

参考资料

[1] 网络安全学习方法之一 - scz 2023-09-07 19:43
https://scz.617.cn/misc/202309071943.txt

[2] 技术写作的首要诀窍 - 阮一峰
https://www.ruanyifeng.com/blog/2024/01/weekly-issue-288.html

本文来自 「曼福吉的分享」https://xiaobot.net/p/MindForge 小报童专栏

详情请见：付费专栏：《曼福吉的分享》