博威---云架构决胜云计算

 找回密码
 注册

QQ登录

只需一步,快速开始

搜索
查看: 211|回复: 0

如何写好一篇技术笔记

[复制链接]
发表于 2024-2-5 06:05:13 | 显示全部楼层 |阅读模式
[color=var(--post-text-color)]
翻看前些年的笔记,发现笔记内容的详尽程度将决定未来能留下来多少有用的知识。不论记性多好,大多数内容都会随着时间遗忘在历史的长河中。在得到听了很多课程,基本上能记住的不多,最终能用上的可能还是记录下来的一些东西,古人云:「不动笔墨不读书」还是挺有道理的。
技术笔记和其他的一般笔记不同,详尽程度将决定笔记的质量,有一些十多年前的笔记我现在已经完全看不懂了,有的文档仅仅写了短短几句,明显没有写完,但真的就再也想不起任何内容了。痛定思痛后,我决定总结一篇如何写技术笔记的文章。
写技术技术记笔记时,应该注意内容
写详细的记录是为了在若干年后,可以重现所有的操作,如果上下文有丢失,将遇到很大的困难。反复学习,不断迭代,所有的积累才能有效累加,为了达到这个目的,写技术笔记至少需要做到以下几点:
    • 完整性:必须包括原始需求、先验知识、现有解决方案、具体实践、参考文献。
    • 具体实践包括不但包括成功的经验还包括失败的尝试
    • 严谨性:所有笔记内容都经过验证,包括参考文献中的结论,没有验证过的就说未验证。
    • 可复现:完整展示环境搭建过程,命令行的所有参数,完整的命令行输出,完整的源代码和编译参数。
    • 深入细节:魔鬼都在细节之中。笔记详细说明各种坑点,关键细节的细微差异。
    • 刨根问底,使用调试器等工具展示底层的细节。
    • 持续性:反复迭代,在自己感兴趣领域的不断积累。

失败的尝试可能是最容易忽略的地方,明明查询了很多资料,尝试了很多不同的方法,最后记录的只有成功的那一条。有一种可能,在极端的情况下,所有的尝试都失败了,是不是就完全放弃了?
如果记录了所有失败的尝试,过一段时间后,你可能重新尝试,但有个前提上下文没有丢失,不然很可能重复走上次失败的尝试。
参考资料的学问
我以前写参考资料的时候,只有一个链接,总是觉得这样就足够了,最近感觉应该要写个标题,这样一下就可以看出参考资料的主题。但如果只记录参考资料的链接和标题,其实是存在信息缺失的。
从技术演进的角度看,文章发表的时间是非常有意义的,从总体上看技术是进步的,我们应该优先学习先进的方法。作者信息则可以让我们认识领域的专家,靠谱的作者的可信度,应该上调一个级别。
scz 在微博上举例利用参考资料的时间信息,搜索的例子:
有些十多年前的微软blog,可能形如:
h__p://blogs.technet.com/b//archive////.aspx
原链接肯定不存在了,其中一部分可以换成下面这种样子去访问
h__ps://learn.microsoft.com/en-us/archive/blogs//
所以,参考资料应该记录:标题、作者、日期、链接
严谨的记录带来一种有序
严谨的记录是对内心的一种拷问,要求不断地问自己是否真搞清楚了,有没有遗漏前提条件,是否只是某种巧合。严谨的记录带来一种新的有序,不断完善的基础概念,不断增加的各种尝试/方法,从而提供跨出知识边界,跳出思维定势的可能性。
记笔记的态度比笔记方法重要
笔记是一笔可以积累的财富,认真写笔记可以在未来的时间里获得复利,态度决定一切,这比所谓第二大脑,卡片笔记法都重要。任何可以持续积累并获得进步的习惯应该坚持下去。对于个人成长来说,不断记录,不断总结,不断分析,才能螺旋前进。
最后
以 scz 的话结尾:
若自己写的技术文档三个月之后乃至更长时间跨度,不能指导自己的相关工作,该文档严重不合格。该标准很靠谱,诸君可自行检验。
参考资料
[1] 网络安全学习方法之一 scz 2023-09-07 19:43
[color=var(--post-link-color)]https://scz.617.cn/misc/202309071943.txt


您需要登录后才可以回帖 登录 | 注册

本版积分规则

小黑屋|手机版|Archiver|boway Inc. ( 冀ICP备10011147号 )

GMT+8, 2024-4-12 19:39 , Processed in 0.142855 second(s), 16 queries .

Powered by Discuz! X3.4

Copyright © 2001-2021, Tencent Cloud.

快速回复 返回顶部 返回列表