这是人月神话：软体专案管理之道（20周年纪念版）的第十五章：一体两面(The other face)，简体版译作另外一面，到是很直觉，而一体两面四个字用起来很像是成语，不过译的是否贴切，有待进一步观察。ㄚ琪从头到尾看完一遍，很抱歉看不出内容跟主题关联的情形，倒是开场白歌德‘What we do not understand we do not possess.’‘我们无法主宰我们不了解的东西’，倒是满贴切的，这一篇对ㄚ琪来说，是个很实用的建议，我应该会把里面的教学做在我的程式里头。本篇的重点就是“如何”写好文件。
该写哪些文件？
为使用程式而写的文件 这里主要针对文件应该先有概观性的描述(overview)，作法引用简体版并译成繁体字使用如下：
1. 目的。主要的功能是什么？开发程式的原因是什么？
2. 环境。程式运行在什么样的机器、硬体配置和作业系统上？
3. 范围。输入的有效范围是什么？允许显示的合法范围是什么？
4. 实现功能和使用的演算法。精确地阐述它做了什么。
5. 输入－输出格式。必须是确切和完整的。
6. 操作指令。包括控制台及输出内容中正常和异常结束的行为。
7. 选项。用户的功能选项有哪些？如何在选项之间进行挑选？
8. 运行时间。在指定的配置下，解决特定规模问题所需要的时间？
9. 精度和校验。期望结果的精确程度？如何进行精度的检测？
这样就可以写出3到4页的摘要性说明，这里头有些ㄚ琪还需要改善自己的文件说明，但是环境常常会省略掉，以后应该会加入进来。
为建立对程式的信心而写的文件 这句话的意思就是增加测试案例(test case)，我倒是没有写这个文件的习惯，改吧。这种文件有三部份：主案例、罕见合法案例及罕见不合法案例。
为修改程式而写的文件 包含的部份：
1. 流程图或副程式的结构图，对此以下有更详细的论述。
2. 对所用演算法的完整描述，或者是对文件中类似描述的引用。
3. 对所用档案规划的解释。
4. 解译阶段结构(pass structure)的概观——从磁片或者磁带中，获取资料或程式处理的序列——以及在每个处理过程必须完成的操作。
5. 初始设计中，对已预见修改的讨论；特性、可插入点(hooks)与离开点(exits)；原作者对可能会扩充的地方以及可能处理方案的一些意见。另外，对隐藏缺陷的观察也同样很有价值。
恼人的流程图
这个流程图到是很让ㄚ琪头痛，因为ㄚ琪从来没有将流程图做出来过，但是在看别人写的程式时，却又很希望作者有流程图可以让人参考，很矛盾吧，好在作者也不建议做流程图，终于有跟ㄚ琪同一阵线的人了，给个赞，但是作者反倒建议将程式转成以执行阶段或步骤为主的结构图，然后画在一页大小的流程图上，倒是满方便的，举例如下图：
这里还引用使徒行传15:10‘现在为什么试探神，要把我们祖宗和我们所不能负的轭放在门徒的颈项上呢？’，当然典故ㄚ琪就不多说了，只能说作者用圣经的话来强烈支持不做流程图，ㄚ琪颇认同这观点。
自我说明程式
这里头建议把书面说明写到程式码里，这样可以大幅改善维护工作，而且保证程式使用者可以随时便利地参考文件，这种作法称为程式的自我说明(self-documenting)，感觉好像Java的说明文件喔，很有可能是有这里衍生出来的。
可行的方案
第一个想法是借助那些出于语言的要求而必须存在的语句，来附加尽可能多的“文件”资讯。因此，标签、宣告、符号名称均可以作为工具，用来向读者表达尽可能多的意思。
第二个方法是尽可能地使用空格和一致的格式提高程式的可读性，表现从属和巢状关系。
第三，以段落注释的形式，向程式中插入必要的叙述性文字。
拒绝去做的理由 我想已经没有理由了吧，Java都弄的吓吓叫了，甚至组合语言也可以这样做吧，那就很cool了，不过这样的文件如果有时来个范例说明，感觉就更好用了，当然这是以在学者的角度来看的。