关于程序员写文档和发帖子的一些看法

年前，部门做知识管理，让每个人把自己负责的模块的一些文档补齐一下，输出一些代码导读或者问题定位之类的帖子。完后，看同事们发的帖子，果然每个人都有不同的行文逻辑和写作风格，有的读起来清晰易懂逻辑顺畅，有的就比较发散很意识流，有的甚至都不知所云。写好文章其实也很重要的，既是对已有工作和知识的总结帮助自己内化，也是对外输出技术影响力的重要手段，甚至都是一些公司的考核KPI了。那么，一篇好的文档或者帖子需要具备什么特点呢？我这里说一下我个人的思考和想法：

• 明确读者受众。一篇文章开始前，就要想好这个问题，是写给自己温故而知新，还是写给其他的开发人员看，又或者写给测试技术支持等非开发者。面向的目标读者直接决定了文章内容的深度和细节。比如：写给测试或者运维，那么就没必要写那么多实现细节，把基本原理和外部关键观测点或者重要操作写清楚才是最重要的。
• 想好题目和关键字。技术类文档和帖子发布出去，绝大部分都是通过搜索来找到的，这就要求把题目和关键字想好。千万不要写特别通用的不包含任何定位关键词的标题，最好可以把产品名/模块名/核心技术名等带进去，容易被搜到点击量才能上去。
• 划分好章节和段落。一个章节聚焦一个主题，段落划分合理，不过长也不过短，让人读起来没那么累，也容易定位到想读的部分。
• 图和表能配尽量配。图表的直观性是显著强与文字的，能够配图表的尽可能的配图表，这点就不赘述了。有个技巧就是，如果是通用原理性的，利用好关键词基本可以Google搜到，省的自己重复造轮子，记得标明出处。
• 涉及代码要明确版本号。毕竟代码演进的速度是很快的，文档可能不能及时更新。这点太多人不注意了，帖子和版本对不上，有时候反而会给人误导。
• 参考文献给出原始链接。引用别人文章的部分，要给出原始链接。原始链接可能后续会更新，这也是对原创的尊重。
• 存疑部分一定明确标出。发帖时一个技术点可能当时自己还没完全理解透，类似代码里的TODO，这时一定要明确标出来，在样式上能够明显分辨，这样一来不误导别人，二来提醒自己后续完善。

写的一手好文章同样是一名优秀程序员的必备技能。一名好的开发者，你不光要对外出输出好的代码，也要能够输出好的文章，把自己的理念和思想广播出去，把自己的技术影响力构筑起来。要知道，很多著名开发者不光写的一手好文章，喷人也是非常厉害 😃