如何写好一篇技术文章

2024-04-17 22:51 由 Super403 发表于 #其他

摘抄网上文章SCZ
来源：scz.617.cn

翻看前些年的笔记，发现笔记内容的详尽程度将决定未来能留下来多少有用的知识。不论记性多好，大多数内容都会随着时间遗忘在历史的长河中。在得到听了很多课程，基本上能记住的不多，最终能用上的可能还是记录下来的一些东西，古人云：「不动笔墨不读书」还是挺有道理的。
技术笔记和其他的一般笔记不同，详尽程度将决定笔记的质量，有一些十多年前的笔记我现在已经完全看不懂了，有的文档仅仅写了短短几句，明显没有写完，但真的就再也想不起任何内容了。痛定思痛后，我决定总结一篇如何写技术笔记的文章。

写技术技术记笔记时，应该注意内容

写详细的记录是为了在若干年后，可以重现所有的操作，如果上下文有丢失，将遇到很大的困难。只有反复学习，不断迭代，所有的积累才能有效累加。而为了达到这个目的，写技术笔记需要做到以下几点：

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

失败的尝试可能是最容易忽略的地方，明明查询了很多资料，尝试了很多不同的方法，最后记录的只有成功的那一条。有一种可能，在极端的情况下，所有的尝试都失败了，是不是就完全放弃了？如果记录了所有失败的尝试，过一段时间后，你可能重新尝试，但有个前提上下文没有丢失，不然很可能重复走上次失败的尝试。

参考资料的学问

我以前写参考资料的时候，只有一个链接，总是觉得这样就足够了，最近感觉应该要写个标题，这样一下就可以看出参考资料的主题。但如果只记录参考资料的链接和标题，其实是存在信息缺失的。
从技术演进的角度看，文章发表的时间是非常有意义的，从总体上看技术是进步的，我们应该优先学习先进的方法。作者信息则可以让我们认识领域的专家，靠谱的作者的可信度，应该上调一个级别。
在微博上举例利用参考资料的时间信息，搜索的例子：

有些十多年前的微软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>

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

严谨的记录带来一种有序

严谨的记录是对内心的一种拷问，要求不断地问自己是否真搞清楚了，有没有遗漏前提条件，是否只是某种巧合。严谨的记录带来一种新的有序，不断完善的基础概念，不断增加的各种尝试/方法，从而提供跨出知识边界，跳出思维定势的可能性。

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

笔记是一笔可以积累的财富，认真写笔记可以在未来的时间里获得复利，态度决定一切，这比所谓第二大脑，卡片笔记法都重要。任何可以持续积累并获得进步的习惯应该坚持下去。对于个人成长来说，不断记录，不断总结，不断分析，才能螺旋前进。

最后

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