如何写好一篇技术文章
摘抄网上文章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>
所以,参考资料应该记录:标题、作者、日期、链接
严谨的记录带来一种有序
严谨的记录是对内心的一种拷问,要求不断地问自己是否真搞清楚了,有没有遗漏前提条件,是否只是某种巧合。严谨的记录带来一种新的有序,不断完善的基础概念,不断增加的各种尝试/方法,从而提供跨出知识边界,跳出思维定势的可能性。
记笔记的态度比笔记方法重要
笔记是一笔可以积累的财富,认真写笔记可以在未来的时间里获得复利,态度决定一切,这比所谓第二大脑,卡片笔记法都重要。任何可以持续积累并获得进步的习惯应该坚持下去。对于个人成长来说,不断记录,不断总结,不断分析,才能螺旋前进。
最后
结尾:若自己写的技术文档三个月之后乃至更长时间跨度,不能指导自己的相关工作,该文档严重不合格。该标准很靠谱,诸君可自行检验。