技术写作的两种方向和方法

最近准备对公司的一个很复杂的项目写一份源码分析，方便以后新人接手的时候能够快速上手，不用像我当初一样太过于痛苦。在浏览源码写作规范的时候，读到了doodlewind的《为什么源码分析味同嚼蜡？浅析技术写作中的思维误区》，深受启发。

技术文章可以分为新人向和老人向，在进行技术类文章写作的时候，要先明确文章受众群体。是面向入门的新手还是已经拥有技术背景的老手。我会总结分析一下二者的一些写作方法。建议各位先阅读上述原文。

秉承的价值观不同

新人向的文章：以读者为本的价值观，关注如何让读者理解知识。

老人向的文章：以规范为本的价值观，关注如何系统、结构地陈列知识。

写作思路不同

新人向文章：写作的时候多问几个why，尽可能剥离业务性的逻辑，关注程序本身的抽象和设计，而不是源码细节。

老人向文章：减少非专业描述语句，写作行文可能更偏向流水账，目的是为了呈现细节。

新人向写作的一些具体技巧

1. 尽量以简单的文字、图片、表格、流程图、简短的代码或者伪代码来进行描述逻辑。绝对避免大段源码粘贴。
2. 不要假设读者的水平。描述应该尽可能细致准确，对于一些与本文无关的概念解释，将关键词连接到其他地方的资料上，这种方式既能保证概念的准确无遗漏，也可以保证书本本身的主题不被其他主题所干扰。
3. 经常举例子，对于一个复杂功能，单纯的描述其作用原理是非常有限的，不利于读者理解。
4. 写作的时候千万不要抱着【我这个东西很厉害呢】的心里，这样写不出优秀的入门类文章的。要旨在分享，希望能够让新人看懂

老人向写作的一些具体技巧

1. 面向老人向写作，并不代表上面对于新人向的写作技巧不能使用。只是针对此类受众，提高文章中的知识密度是更重要的事情。例如专业文献、专业书籍等。此类文章，是需要给已经读懂过一次的人，才能发挥出最大的价值。
2. 注重逻辑、珍惜笔墨、减少非专业描述语句。

结语

写文章的时候，注意分析受众的身份，不要混淆，不然的话很容易让读者感到困惑。本文其实算是老人向的文章，针对的是看过doodlewind的《为什么源码分析味同嚼蜡？浅析技术写作中的思维误区》，从中获得的启发。也欢迎大家继续补充～