在任一描述性的文档里,都应该能够找到至少5个W和1个H。

  1. Why -为什么?为什么要这么做? 写出原因。 
  2. What - 是什么? 做什么?
  3. Where - 何处? 在哪里做? 从哪里入手?
  4. When - 何时? 什么时候完成? 什么时机最合适?
  5. Who - 谁? 由谁来承担? 谁来完成? 谁来负责?
  6. How - 怎么做? 如何实施? 交代出具体的实施过程。

就德利的源代码描述性文件而言,文件内容包含的必要元素有以下内容:

文档必须明确解释到为什么需要专门创建1个单独的源代码文件, 并进一步解释这么做有什么好处。

该源代码文件的出现和存在会对其他源代码文件产生什么影响?它是如何联动这些源代码的。技术文档要明确将这些源代码文件名字罗列出来。这包括,但不局限于当前这些源代码所被连接的链路。

同时,技术文件还要解释该源代码需要依赖哪一些源代码文件才能发生作用。这些源代码文件名字需要一一列明,并提供连接的链路。

该源代码的初版作者是谁、当前的版本作者是谁?各个版本号以及作者是谁?他们的最新联系方式、当前的源代码文件运用到什么具体的位置?已经归档的该源代码档案存放的位置在哪里? 当前的维护者是谁?以及其联系方式。

对于被替换下来的源代码文件,管理者都需要在源代码文件开头用明显的字眼标注「注销」。还要说明被「注销」和替换下来的原因和理由;以及是否已经有替换的源代码文件补上。如果有,就说明替换其作用的源代码文件名称、作者名字、联系方式,等。

每个技术文档的内容都必须包含对应的源代码相一致的作用机制陈述。

每一个德利技术文档都必须有与该文件对应的源代码文件相一致的伪代码。

 下面说明5w1H法的应用程序 1、检查原产品的合理性 2、找出主要优缺点 如果现行的做法或产品经过七个问题的审核已无懈可击,便可认为这一做法或产品可取。如果七个问题中有一个答复不能令人满意,则表示这方面有改进余地。如果哪方面的答复有独创的优点,则可以扩大产品这方面的效用。 3、决定设计新产品 克服原产品的缺点,扩大原产品独特优点的效用

在發行新修改的技術文檔之前,務必要反覆運用5個W 和1個H來檢驗技術文檔的各個方面表述的完整性。如果當時的文檔內容經無法找到6個問題的答案,則說明該文還有改進的餘地。如果是肯定的,則說明該內容的表述至少是可用的。

德利的技术文档也可运用到对一个组件、什么一个模块的特性描述。内容包括但不限于,该内容业务功能(为什么要创建这个该内容)、该结构由多少个源代码文件组成、每个文件存在的意义、文件中每个函数或对象的详细运行步骤,并且以伪代码的方式描述,尽可能做到通俗易懂。

格式

一个标准的德利技术文件的结构、元素及其次序。

文件名字

版本号

版权声明

拥有者-包括其联系方式

摘要

目标

适用范围(适用性)

调用和被调用的有关源代码文件及其链接

内容1. 解决方案

内容2. 伪代码

内容3 API

参考资料

该段落要提及那几个有关的源代码文件,包括其链接路径;这几个相关的源代码技术文件及其链路。

历史版本

需要介绍各版本迭代原因或理由;以及每个版本的主要变化的部份。