技术文档编写首先寻找资料,阅读资料可以和编写文档同时进行,即编写段落一时查询段落一的相关资料,当编写到后面的段落时,发现和前面的段落有冲突,在回头整改,整个过程类似于ABSD和螺旋开发模式。
第一部分技术文档的开头无外乎背景、目标、范围、参考资料等等,这些是纯商务描述,有成型的资料最好,不然就只能在众多资料阅读后,自己编写。
第二部分技术文档编写通常是指系统设计或者系统相关资料,系统的设计与开放的目的自然就是首要位置,其次就是系统的约束,有哪些规则约束的当前系统。最后设计原则或者方法,我们要用什么样的方法去设计系统。
第三部分就是系统设计完成状态的展示,展示首先是总体展示,总体展示可细分为很多项,可以根据项目自行选择,如整体用例图、拓扑图、结构图,当然总体系统描述是不可缺少的。
之后是主要功能展示,即大项目是子系统或者模块描述,小系统是功能描述。
第四部分是决策,该部分并不是必须的,但是,如果当前技术文档是展示重构或者有类似的功能调整或者技术调整或者架构调整时,该部分是必不可少的,决策很简单,只要描述变更点就可以了。
第五部分我称之为边界,该部分描述与系统连接的内容,比如接口、数据库等,这些内容是系统的一部分,但又不在模块之中,所以单独拿了出来。另外,如果当前文档有第四部分,则边界的编写则需涵盖变更点。
第六部分扩展,扩展即可移植性、可扩展性、可维护性、可配置性等描述。
第七部分是性能与安全,性能与安全可以并存也可以只有其一,如果是小系统甚至可以不描述。
第八部分是故障,该部分可以有,也可以没有。
第九部分是总结,总结当前文档,描述当前文档实现后的结果,即愿景。这个部分也是可有可无。