技术文章的写作思维
后台有许多同学留言问我:为什么我一方面可以日更,另一方面文章可读性也比较友好,不会太晦涩难懂。
最近在抽空整理之前的一些学习笔记和文章草稿,在整理的过程中,我也在思考如何持续的输出高质量的文章。
这背后一方面需要大量的知识储备和实践;但更重要的,我认为是清晰的结构性思维。即主题是否明确,大纲逻辑是否清晰,内容是否有例可循,结论是否切中要点。
今天这篇文章, 我想聊聊写技术文章背后的一些写作思维,或者说结构体系。
其实在我看来,无论是日常工作中写技术方案、测试报告,还是写技术文章或者工程实践手册,都是有法可循的。只要抓住如下图的六点要素,就可以写出很好的技术文章。
背景/前言/原因
以技术方案为例,假设我们要输出一个项目的技术设计方案,开头要怎么写?一般来说都是先说明背景,即这个项目是什么,为什么立项,要解决什么问题,预期目标是什么,何时交付。
如写一篇技术文章,开头要说明什么?比如提测质量不高,为了提升编码质量打算做单元测试。业内的方案有ABCD,我们当前的现状是XXX。
遇到的问题/面临的挑战
说明背景和原因后,接下来就是介绍当前的背景,比如遇到了什么问题,由于什么原因导致可能存在什么风险。比如项目交付周期很紧急,时间资源不足。
比如多个项目并行,但只有一套测试环境,环境资源无法调度开。比如做自动化测试,造测试数据耗时很长,原因是没有数据库的权限,无法批量生成。
如何解决?思路&方案介绍
说明了背景,阐述了遇到的问题和可能存在的风险,接下来要介绍具体的分析思路和解决方案。
假设我想写原创的公众号技术文章,但是我以前写的不多,也没有太多的知识储备,我该如何解决呢?
- 写的不多:搜索知名的技术博主,看他们是如何写的。用的编辑器,文章结构等;
- 知识储备不足:日常工作中遇到的问题,分析的过程和解决方案,做好记录,多复盘总结;
- 输出技术文章:将日常记录的零碎笔记,问题解决方案,复盘后自己的理解写出来,找朋友或者同事帮你review,给你多提建议或者他们的阅读感受,然后如此坚持即可;
再假设我要做自动化测试,手动造数据耗时太长,没有数据库操作权限,该怎么解决呢?
- 搜索业内比较好的解决方案,比如数据工厂模式;
- 调研他们的实现方式,没有数据库权限就通过调用接口去写入数据;
- 按照业务场景划分P0P1P2优先级,先把最核心的场景数据造出来,实现从零到一的突破;
- 不断优化这种方式,最终封装成一个平台,赋能给其他业务线的测试甚至开发/产品使用;
实践的过程/解决了什么问题
很多技术方案的落地过程都会遇到问题,比如信息同步问题,比如版本兼容问题,比如网络问题。
如上面提到的自动化测试造数据没有数据库权限,那就通过调用接口去实现写入。如果开发没有提供接口文档或者团队内部的研发规范不足,就自己去抓包或者review代码去整理接口文档。
做这些事情的过程就是解决问题的过程,在日常工作中会发现很多存在的不足,为了达成我们的目标,可能要多做很多没有直接联系的事情,但正是这些事,才是我们真正的产出和价值的体现。
总结/经验/教训/结论/最佳实践
一个技术方案或者一篇技术文章,最后一定要说明结论。比如某种技术框架的落地效果,比如落地过程要注意哪些事项,比如什么类型的业务更推荐哪种技术方案来解决,比如落地后是否解决了其他相关的问题。
从技术输出的角度来说,最终的结论要么是总结经验,要么是吸取教训,要么是沉淀输出最佳实践案例。
展望/未来规划
有背景有目标有方案有过程有结果,最后如果补充一些和主题有关的未来展望或者落地规划,会是一个很好的点睛之笔。
我个人的经验,技术文章写作思维,或者说专业性较强的文章或者方案,在写作时只需要记住这几个关键词即可:目标明确、逻辑清晰、有过程有结果有结论、避免口语化表达。
最后,以最近几个月大火的ChatGPT来说,我要写一篇ChatGPT的技术实践落地文章。我会这么写:
背景:ChatGPT的由来、特点;
遇到的问题:我们的现状是XXX,而ChatGPT更适合解决YYY类型的问题;
解决的方案:经过调研发现ChatGPT只能解决某部分的问题,其他部分可以采用ZZZ方案;
实践的过程:落地过程中发现我们的基础设施不足(如元数据管理混乱),我们的解决方法是XYZ;
实践经验和结论:ChatGPT更适合某类型的业务,在我们当前的业务场景中落地的投入产出比没那么高;
未来计划:假设ChatGPT未来可以强化某方面的能力,我们的业务多元化之后,可以更好的利用ChatGPT来提高效率。当前还是保持内部小范围的试验,积累能力,做好基础设施建设。