写技术博客的注意事项

个人认为写博客（Blogging）是技术总结的最佳方式，甚至可以这样子讲，博客就是积累，从一定角度上讲是酱紫的。可能是受规范约束习惯了，感觉写博客也有一些注意事项，虽然之前写了很多文章，但感觉都不是很规范，现总结写博客应该注意的几点，以随时提醒自己。

1. Do not Repeat Documents, link to it   不要重复文档，给出链接就好。重点写自己的心得，体会和总结。

对于那些在官方文档中都讲的很清楚的东西就没有必要再进行重复了，给出相应的链接就好 了。特别是对于像MSDN这种非常丰富的官方文档，最好不要去重复它的内容，因为你不一定比官方讲的清楚。重点应该放在自己的心得，体会和总结等，这样于 自己是真正的总结和积累，能变成经验，于他人也是一种有价值的参考的。

2. 进行全面的总结

前面说了不要重复文档，那应该写什么呢？愚认为，应该是自己经过实践之后的总结：

• 把所有可靠的方法都说一下;

• 把注意事项说一下;

• 把各种方法进行比较，给出各自的优缺点和适用场合;

• 文档中没有说明的情况，比如对文档的补充，或者文档有自相矛盾的地方。

3. 必须亲自实践进行验证，确保可靠可行。并附上实例（源码，资源）和运行结果（截图等）

4. 要总结与所谈内容相关且有价值的网络资料

5. 要列出参考资料，比如官方文档，别人的博客，源码等。这是对别人的尊重，也是对知识的一种尊重。

6. 可以参考，可以引用，但不要照搬，不思考式的抄袭。最重要的是要有自己的思考和理解。

如果是受他人的博客或代码的启发，最好把关键的句子段落引用出来，然后再写自己的思考和讨论。在文章中再给出原文或出处的链接，这样以显得尊重和专业。

7. 最好能有版本控制信息和修订记录

对于代码我们都有版本控制系统来帮助维护修改记录。但对于文档，也建议这样做。对于博 客，可能没有（或许我不知道）类似的工具，但可以手动来说明。比如在博客的头部或尾部加上修订历史记录，或者在文章中把后来的修改用其他字体标明，或者用 括号或脚注来说明。这样自已日后看起来也很方便，也能看到自己的思考过程和成长过程。

8. Less But Better精深原则

讲的越详细越好，范围越小越好，但要深入的讲，正如那句话，十个百分之十不如一个百分 之百。如果你不能深入的讲，证明你还没有到写的时候，应试再去学习或者实践，直到你能讲的很清楚，讲的很详细，讲的很深入的时候再来总结和写博客。争取做 到一篇文章一个点，这样文章多了就成了网最后变成没有漏洞的面。

9. 突出主题，分清主次，逻辑清楚，层次分明

这可能是对于写作的通用要求，说起来容易，但是做起来就比较困难。其实也不难，主要表现在：

• 列表来罗列要讲的东西
• 用标题先简明概括，然后再详细讲解
• 标题与正文用不同的字体样式标识
• 用字体和缩进来标识标题和正文

有没有一种感觉，这好像是在讲编码规范，没错，很早就有人讲过，写文章跟写代码是一样的。所以，作为程序员的我们，可以考虑用写代码的一切，包括习惯，规范来写文章。

10. 写完后多读几遍，进行校改

这就好比写完代码后的调试与测试。好代码是改出来的，好文章也是如此。能够一蹴而就的 人有，但很少。即使是像鲁迅那样的大作家写文章都还需要修改，都没有一次成型的，更何况我们呢？在写完文章后也视情况对文章进行调试和重构，直到自己读起 来感到满意和舒服为止。试想，如果自己写的文章自已都不想看，别人会看吗？我们又不是在写作业，不管好坏老师总会看，而且要仔细的看。要想写出好文章，必 须首先让自己认为是好文章。

11. 用通俗易懂的平实的语言，对于专业术语要解释

好的技术文章应该都非常容易看懂，即使你对所说的那门科学完全不知。去读一读 《Code Complete》等之类的经典书籍的英文原版，你会发现，其实看原版书并不需要多么NB的英语水平，可以不客气的讲上过大学的人应该都能看懂。其实这重 点不在你懂不懂英语，而是要看作者能否用最易懂的语言来把事情表达清楚。这确实是一种能力，平常我们所谓的沟通能力，也基本上就在这，看你能否用最简单的 语言把事情表达清楚，让另一方听明白。

这里有一些技巧：

• 多用比喻，用大家熟悉的东西来比喻，这是让人最容易理解的一种方式。比如把软件构建比作建房子;把软件架构师比作楼房的设计师等。
• 多用图示，用图解。很多时候一张图能抵上几百字的文字叙述，但还不一定能说明白。给出一张图就什么都明明白白了。
• 图文并茂是讲解的最佳方式，合理的安排图片，再加之文字描述会达到事半功倍的效果。

12. 用事实说话

有图有真相，有代码有真相。说完了，讲过了，最好附上真实事例，代码和截图。否则别人可能会质疑，至少我在看到别人只“说”，没“做”的时候会质疑的。