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

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

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

秉承的价值观不同

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

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

写作思路不同

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

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

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

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

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

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

结语

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

技术写作的两种方向和方法相关推荐

【转载】面向对象建模与数据库建模两种分析设计方法的比较
[转载]面向对象建模与数据库建模两种分析设计方法的比较板桥里人 http://www.jdon.com 2007/9/23(转载请保留) 我们知道:一个软件从无到有需要经过如下几个阶段:分析.设计. ...
史上最容易理解————GET和POST两种基本请求方法的区别
GET和POST两种基本请求方法的区别 GET和POST是HTTP请求的两种基本方法,要说它们的区别,接触过WEB开发的人都能说出一二. 最直观的区别就是GET把参数包含在URL中,POST通过req ...
GET和POST两种基本请求方法的区别
GET和POST两种基本请求方法的区别回退回退时无害会再次提交请求记录 URL可被记录, 用于再访问不可以缓存主动缓存可手动设置编码方式只进行url编码多种编码方式参数长度有 ...
哈希查找解决地址冲突的两种最常见方法（线性探测再散列，链地址法）C++实现
哈希查找解决地址冲突的两种最常见方法(线性探测再散列,链地址法)C++实现参考文章: (1)哈希查找解决地址冲突的两种最常见方法(线性探测再散列,链地址法)C++实现 (2)https://www. ...
fstream与 C 风格（例如fread 和 fwrite ）两种读写文件方法的效率比较
我觉得作者写的挺好,评论也写的很对. 目前我的项目就是在VS2008+Qt+win7上开发的.我上次总结的QFile和C语言对文件操作的性能比较.--读取double型二进制数据文件也说明了这个问题. ...
Ｗord 2003中打开最近操作过的文档的两种推荐的方法
本文介绍Word 2003中打开最近操作过的文档的两种推荐的方法. 注:我的系统为WINDOWS 7,与XP下基本一致. 方法1: 在WINDOWS 7下,点击任务栏上的WINDOWS图标(即&quo ...
【H5】两种加密解密方法：
[H5]两种加密解码方法: encodeURI(): //加密 decodeURI(); //解密加密成base64编码格式 btoa() 加密 atob() 解密实现代码如下: <!DOC ...
js两种拼接字符串方法
js两种拼接字符串方法 function(msgArr) {//参数为一个数组,每一个对象为图片id和图片地址var len = msgArr.length;//第一种拼接方式,直接用"+& ...
R中两种常用并行方法——2. snowfall
上一篇博客(R中两种常用并行方法--1. parallel)中已经介绍了R中常见的一种并行包:parallel,其有着简单便捷等优势,其实缺点也是非常明显,就是很不稳定.很多时候我们将大量的计算任务挂 ...