1.记录文档的坚持实用的原则

1.1.注意整体的观念

  一定要从整体和实用的角度去记录，零零散散记录一些关键点或难点几乎是没有意义的，这也是我以前所犯的一个错误。

  如果不是特殊需要，尽量不要去剖析一些整体源码的内部算法，尽可能以整体的形式去应用其。一则算法和源码时不断更新的，现在的剖析很有可能在未来毫无意义。二则现实很少有这种需求。三则应该先怀疑自己，而不是源码的错误。

1.2.以读者为中心书写文档

除了以固定的格式书写文档外，还应该以读者为中心。所谓以读者为中心，简单的说，就是读者需要什么，就写什么。读者最需要的东西应该放在最显眼的地方，要多写。读者不太需要的东西，应该放在次要的地方，要少写。

写文档也应该注意目标导向。

1.2.1.读文档逻辑和写文档逻辑

即所谓的表达思路和理解思路。写文档的人应该尽可能使表达思路等于理解思路。对文档的不断修改、就是使表达思路日趋接近理解思路。

表达需要，按作者的思路将内容表达出来，由于专业背景、个人特点等原因，作者的思路不一定是读者易于理解的思路。所以必须经过多次迭代修改，将其转换为读者的思路。读者的思路具有如下特点。

  简洁。用尽可能少的字，表达尽可能多的意思。

  由浅入深。

  介绍足够背景知识。

1.2.2.尽可能使用形象化表达的方式

特别是对那些比较抽象，不易理解的内容。图表的方式易于理解，可以大大节约理解所需的时间和精力。

图表表达比较形象，称作形象化的表达。对一个问题形象化表达的过程，也是自己加深理解的一个过程。如果对某个问题需要深刻理解，形象化表达式必须的。

最近在阅读一些论文时，不管是什么主题，首先是一大片公式，让人一头雾水。所以，在说明这类问题时，首先应该说明目的、基本思路、基本原理等。最好是以图、表等形象化的方式表达。

感觉有必要在笔记中增加形象化的内容，因为在下一次阅读书籍和笔记时，觉得很有必要。形像花的内容包括两部分:需求形象化和难点形象化。所谓需求形象化，就是使用频率高的内容形象化。

最近发现了一个系列的图书，即图解系列的图书。主要是日本人书写。非常的形象和直观，便于理解和形成整体的概念。体现了大和民族的精益求精和实用主义精神。非常值得学习。

形象化总结的价值。在以前的工作中，有这样一种感觉，形象化总结可以加速构建的过程，因为使用具体流程、各个模块的功能、使用的接口名称一目了了然，特别有助于形成整体的结构，在大脑中。

2.文档的分类

2.1.过程文档和结果文档

  过程文档

过程文档。记录研发过程的文档，内容包括:项目规划、需求分析、可行性分析、任务模块划分(中间可验证原则和优先级原则)、设计实现、测试、代码质量检查等。

除了以上内容，还有项目的工作经验总结，包括专业知识、工作流程、项目管理、沟通协作等多项内容。为以后高效的工作奠定基础。

过程文档的阅读对象是开发者。其详细说明项目开发的所有内容，包括成功的和失败的。其本质为项目管理文档。

  结果文档(最终开发内容文档)

结果文档，阅读对象时从未接触过项目的人。主要目的是说明项目。包括需求分析、系统架构和实现流程、系统各项指标的测试结果等。

在书写结果文档时，必须充分考虑到读者的需求。力求简要扼要，一目了然，不要浪费别人的时间。即不要写多余的内容。

2.2.学习文档的分类和内容

2.2.1.学习文档如何分类

在开始时,学习文档以一种自由的形式分类;因为内容较少,即便是以自由形式分类，也便于查阅。

当内容较多时，首选以手册的内容分类为参考，因为手册是最权威的资料，其分类应该是最合适的。如果没有手册，可以以经典书籍分类方式分类。

2.2.2.学习文档和两种内容

在文档记录中，应该记录两类内容。

  一是必然经常用到且没有深度的内容。

  二是不经常用到且很有深度的内容。

因为文档记录的目的是未来更加高效的工作。在经常用到且没有深度的内容上，我做的不够。

2.3.计划开发文档和探索开发文档

计划开发常用于可预见性的开发中，在计划性开发文档中，必须详细规划每一个细节，甚至包括结构体的定义，变量的命名等。计划性文档规划的尽可能的详细，以便执行时快速和高效。计划性文档的另外一个目的是，快速理解系统。

探索性文档的目的是，快速理解系统。所以，凡是能够在代码中说明白的，无需在文档中体现。所以文档中内容主要是系统的整体架构和执行流程。

3.文档内容

3.1.优秀文档的四个特征:无错别字、内容组织、排版布局、表达精炼。

在书写文档时，要让对方快速领会自己的意思。需要如下四个方面注意。

1错别字。在用拼音输入时，经常会输入错别字。如何避免这个问题，具体如下。

  人工校对。

  整词进行输入。

  使用word本身的校对功能。Word2013对此的支持较好。Office2013有官方的中文校对软件。但软件校对的效果欠佳。

2组织。组织的目的为两个:便于理解和检查。为了便于检查，在内容组织上，可以通过类别进行组织，并且在文档末尾有索引表。为了便于理解，应该介绍背景和相关知识，由浅入深，循序渐进的说明问题。

3排版布局。详见word排版相关内容。

4精炼。用最少的文字表达一个意思。在写完文档1+小时后，自己反复锤炼几遍，将冗余的文字去掉，尽量用简洁的表达方式。文档中每一个细节(比如每个字，每个排版的细节等等)，都应该为中心思想服务；对中心思想上都是给力的。

3.2.文档中加入搜索关键字和相关专业

在当今的开发中，关键字的管理越来越重要，因为体系越来越庞大，搜索工具越来越先进。所以，关键字的确立和含义非常的重要，如何快速的确立关键字，提一下点。

  透彻理解概念，准确全面的设立关键字，理解别人提出的关键字。

  在学习和开发文档中，记录关键字及其含义。

  注意关键的多种表达方式，比如简写形式或同义字。

因为好的高效的关键字需要不断的提炼，可以将其作为后续开发的几个基础。关键字应I该有英文，因为可能查阅英文文档。

在记录专业文档时，应该记录相关的学科。比如计算机图形学，相关学科是计算机视觉、计算几何等。以便于资料的查阅。

3.3.分散逻辑的问题

在代码系统中,有些逻辑不是集中在某个模块实现,而是分散在多个模块实现。这种分散实现的模式为代码管理提供了很大的困难。以如下方式进行管理。

  以文档的形式记录整个逻辑流程。

  逻辑所涉及的函数，以及和逻辑流程的关系。

  在代码中添加足够详细的注释。注意注释和文档保持一致。

  注释应该说明代码的逻辑含义。如果有必要，应该说明其与上层逻辑的关系。

3.4.专业积累的记录的内容论述

以前就这个方面做出了论述，主要是重点和难点。对于重点而言，需要形象化描述，做到一眼看穿器本质的功效，使下一次迅速进入状态。对于难点，需要多加注释。比如流程和基本原理的概述，这属于重点内容，需要形象化描述，目的就是在最短的时间内，看穿其本质。

还有一个方面也很重要，就是文献综述。介绍每个文献的作用和查阅方法，这个非常重要，因为可以极大的提高效率。

似乎和论文的开始部分十分的相似，不过无需介绍背景部分，因为这方面的资料太多了，实在不行百度百科也可以。

3.5.想写书一样积累自己的专业知识

在长时间的专业积累过程中，总结出许多方法。比如难点说明、概念、形象化描述。却没有从整体上加以总结。如果总结的话，就一句像写书一样总结自己的专业。这里的书，当然不是随便的一本书，而是一些经典书籍。

比如算法和原理说明的教材类书籍:算法导论、编译原理、计算机程序设计艺术。、

一些系统应用类书籍。<>、<<现代x86汇编语言程序设计>>等。

我的需求是什么呢？是工程解决问题，应该从如下几个方面积累。

  书籍文献说明。相当于论文综述。比如有的书比较全面、有的书说明问题比较形像化、有的书概念说明的比较详细。这些都要说明。

  系统总体流程说明。这个非常重要，让你懂得你所阅读在整体中的价值和地位。让你在工作和学习中更加有目标。一定要以图、表、例子形象化的说明。

  系统难点剖析。主要这里的难点，是针对你个人的，而非其他人。因为这是为自己以后更加高效的工作。

  源码。一定要有源码部分，并且能跑通。有着完善 的注释。

  不要重复其他书籍中内容。如果完全一样，完全没有必要再记录一遍，除非有进一步的深化或理解。

3.6.技术文档应该记录些什么

3.6.1.算法文档的内容

原则:尽可能在代码(包括代码和注释)中说明问题。因为代码更加直接。

目标:下次查阅时，可以直接定位算法或问题在代码中的位置。

需要记录的内容1:大块的算法流程。比如运动搜索、熵编码等

  尽量以形象化的方式表达。

  每个节点的内容>=一个底层算法模块。因为模块内的东西可以以代码或注释的形式表示，没有必要单列一个流程节点。

需要记录内容2:一个模块内的复杂流程。

  算法流程非常的复杂，无法通过阅读理清。

  算法流程无关的东西太多，需要提取其骨架。

需要记录内容3:复杂算法的公式表示。有些复杂算法，代码实现和公式表达存在着较大的差异，需要特别指出。

3.6.2.开发文档的内容

  应该详细记录技术的实现的应用背景，目的。即所谓的需求。

  关键代码和模块应该注释。

  文档中应该记录项目的进展情况。如果没有完成，应该说明理由，以供以后参考。

经过这一次的经历，感觉应该梳理一下自己的文档的内容格式了。这个其实很简单，参考经典书籍和论文，结合自己的经意即可。

1）概述。概述应该写什么呢？主要包括如下方面。

  整体技术的结构及所所实现的功能，最好以流程图或其他形象化的方式表示。由于是技术文档，个人认为没有必要书写商业上或社会上的东西，因为这是技术文档。

  文档所描述的系统在整体系统中的位置。

  调研内容。主要的参考文献和关键字。

  实现当前系统的目标。或者是实现某个功能，或者是为了解决某个问题，或者是由于其他系统有一些缺点。

2）构建和可行性研究

确定系统的整体实现流程。审视每个点的可行性。如果觉得模棱两可，则细化目标，直到其可以审视可行性为止。如果无法确定，需要研究其可行性。一般为论文查询，现有产品的调研，专家的咨询。如果无法解决，则需要自己进行一些研究工作。

3）目标细化和工作计划的指定。

细化目标，直到其可以估算出工作量为止。确定每一部分的工作量和工作依赖关系，给出每一部分的工作时间段，及其输入和输出。

4）整体结构的详细介绍。

包括算法流程、实现流程等。这些都是在代码注释中无法直接表达的内容。

5)系统的性能指标。

6）具体进展和展望。

在工作全部完成准备提交时，如果工作完成，应该书写系统的仍然存在的问题，及未来的展望。如果没要完成，则应该书写项目的具体进展，没有将工作进行下去的原因。

7）系统的编译，各部分代码的功能。这个不在正式文档中实现，应该安排在readme文件中。因为这部分是纯形式的东西，未来的变换可能较大，所以应该另列文档书写。

3.6.3.什么的内容没必要记录

其实没有必要什么都写文档。首先没有保存价值的东西，就没有必要记录。其次是大脑足够掌控的东西，在工作过程中没有必要写文档，只要在工作结束时书写文档即可。

4.其他

4.1.代码和文档

4.1.1.李云的观点

李云在博客http://yunli.blog.51cto.com/831344/966154中写了代码即文档，现简要总结如下。

  IT开发文档分为两类，流程文档和设计文档。流程文档侧重于操作流程，比如测试文档、环境搭建文档等。

  代码和设计文档位于不同的抽象层面，文档位于较高的抽象层面，代码位于较低的抽象层面。代码是具体实现，文档从需求到设计，所以设计文档应该着重于总结和抽象。

  设计文档应该着重于设计思路，其直接短路了阅读代码时从代码回朔软件设计的思维过程。

  所以文档应该包括不限于如下内容:需求分析、软件设计、复杂的实现流程(仅凭阅读代码和注释无法快速理解的逻辑)、命名规则、接口定义和说明、开发者的测试和验证流程等。

  设计文档应该点到为止。个人这样理解，能在代码和注释中说明白的，不在文档中说明。

  文档有助于传承团队知识和沉淀工作经验。相信没有人愿意看到如火如荼的项目因为某位团队成员的离开而“熄火”，也不愿碰到因为人员的流动给自己的工作带来极大的痛苦，知识和经验教训的文档化有助于我们缓解甚至克服这类问题。

4.2.如何处理过去的文档

如何处理过去的设计文档？这是一个很大的问题，今天又把我控住了。如何面对这个问题，从两个方面进行。

  过去有，现在也有。现在是过去的增加和补充。这种文档，将过去的隐藏在过去的版本中就可以了。

  过去有，现在没有。将过去的部分单独保存一个文档，存储起来。

4.3.以文档体系取代单个文档

以前写技术文档时，总是要么写一个文档，要么总是写一堆小文档。其实这是不对的。如果只写一个文档，文档和代码的对应感不是很强；如果直接从中载取子系统时，还需要继续从总的文档中提取分文档。如果只写小文档，各个子系统之间的关系无法描述。最好的办法是:

  在总的文档中，重点描述各个子系统的关系。

  子文档中，重点描述子系统。

总体和公共的部分写在高层文档中，细节和局部的部分写在底层文档中。

4.4.readme文件应该划归于代码中

过去在readme文件时，经常会将其划归到文档中。主要代码的基本信息(基于代码的来源及其版、实现功能的概述)和使用步骤。其和代码更加接近，应该划归与代码中。

技术性的信息写入文档中(doc),非技术性的信息写入readme中。

4.5.文档命名问题

在书写文档时，术语和规定重要性。因为并不是所有的名词都能在公共的词汇中找到或在人们的口语中有统一的表达形式，所处需要具体的规定这些词汇的表达形式。这种规定应该坚持如下原则:准确、权威、符合绝大多数人的习惯。如何获取这些名词:按重要性排序如下:词典，比如百度百科等->专业书籍->百度网页的内容。

如何规范文档中的命名？在最近书写文档的过程中，出现了命名比较混乱的问题，需要进一步的规范，以形成好的习惯，增加工作效率。

1、几何元的命名，用大写字母表示点(比如ABC)，用两个点表示直线或线段，用三个点表示平面。

2、自变量的命名，采用一个小写字母,常用的有x y z,u v w;

3、公式系数的命名。采用一个大写字母。比如ABC，MNP，RTS等。

4、角度以希腊字母命名:比如αβγθ等。

5、其他变量采用小写字母的策略，比如l等。

6、取名时按照字母顺序，不要顺便进行。

标签：形象化,代码,软件工程,内容,文档,应该,流程
来源： https://blog.csdn.net/great_sea/article/details/118253663