软件工程文档写作实验一——软件文档之我见

对于文档知识的了解

在我看来，软件文档是由不同的软件制作的不同形式的对于项目的解释说明，软件文档有很多分类，开发人员要根据实际情况决定都需要写什么类型的文档。

自己的开发实践中文档编写的情况

第一次写文档是在软件需求工程这门课上，它的理论课作业和实验课作业都包含了大量的文档写作内容，对于当时没有任何项目开发经验的我来说是一个不小的挑战，好在这些文档基本上都是关于软件需求的，没有很强的硬性指标，简单构思一下项目需要什么功能，根据功能就可以大概确定需求。由于当时只是凭空想象，文档没有实际应用的机会，所以一定存在着很多潜在的漏洞，也更不用说重要性了，当时完成作业也是不够认真。

后来大三上学期的软件综合能力开发训练和软件项目管理让我渐渐从实际上认识到了软件开发的条理性，它的管理、进度、规划安排都是非常重要的，每天都在关心着进度，也会经常性地检查一下文档是否更新、是否保持与现在的进度同步，回看我们写过的文档，发现软件文档确实具有比较强的规范能力和约束能力，让很多不断被讨论的问题成为了所有开发人员的共识，我们能将精力更多地投入在开发上。

综合开发训练的时候，每天要开一次站立会议，并且记录会议内容，我作为组长，时常觉得其实进度规划在一开始就商量好了，干嘛还要开这个会议，每天开会大家也不知道说什么，我就安排分别汇报一下自己小组昨天的进度和遇到的问题、我们今天的规划和目标、小组之间的沟通有没有存在误解等等，聊起来了之后发现能说的还确实不少，于是这个站立会议我们也就认真记录着。还有当时的软件需求说明，一开始做的时候确实是什么也想不出来，在写的时候又是挤牙膏似的，想一点写一点，内容不全面，条理不清晰，往往在开发的时候才查缺补漏，发现漏掉某个需求或是某个需求代码不好实现只是理想太丰满这种情况。不过不得不说，软件需求说明书在开发的时候所起到的效果是很大的，任何开发人员不可能记住所有的需求和功能，包括建立数据库、建立逻辑关系这些前期准备工作，他们在写代码的时候只能按照需求说明书来一步步照做，当时怎么想的，现在就得怎么来，不能出现有一个好点子就加上，觉得某个点不好就删去这种主观因素，否则团队协作就会出现很大的问题，就要用更多的时间去弥补。开发阶段主观因素要尽可能减少，保持团队的一致性。

前文提到的软件项目管理这门课，文档更加多、更加繁琐和规范，我们小组十四个人，我负责管理文档写作的分配，当时写了一些对于项目开发没有太大意义的文档，比如硬件报价和薪资统计等等，实现文档的方式也更多，包括但不限于Excel表格、MS Project等等，虽然这些文档看似意义不大，但我明确感觉到它们的重要性，在真正开发项目的时候这些文档缺一不可。

再后来就是临近寒假和一位校内的老师达成了雇佣关系给他做一个教学网站，这才开始了我的第一个实际项目。我们这次的态度很认真，因为团队成员都明白这不同于平时交的作业，这是真正要用到实处的项目，如果前期准备不认真、不充分，后期会损失很多的时间和精力去修补。我们与老师不断地商量并确认需求，并且严格按照文档上的要求去执行，因为开发时间很长，很容易忘记之前口头约定好的事情，所以一定要有记录，这便是软件文档写作存在的意义。

自己对于软件开发活动中写文档的态度

我的态度就是，文档写作必不可少。虽然代码中可以用注释解释清楚，但代码和注释不能完全取代文档，代码中的注释，通常只属于对它所在的那个源文件，通常是一个方法、属性的注释与说明，这些说明的内容通常是局部性的，它们只属于当前的类文件，所以代码+注释有比较大的局限性。

其实反过来想，文档对于项目的作用恰恰就是注释对于代码的作用，通常我们实现一个复杂的算法后，都会在关键步骤上加上注释和说明，并且还会在文件头加上算法的功能及其标准输入和预期输出，这都能体现出开发人员对于写过的代码容易忘记，对于复杂的逻辑容易混淆，就像笔记一样，清晰的条理能使开发人员更快捷地想起来之前写过什么，之前是怎么做的，还有将要实现什么功能（如注释中的"//TODO"），软件文档也是同样的道理，一套规范的软件文档就等价于代码文件里完整的注释一样。注释使得代码更容易阅读和套用，软件文档使得软件项目更容易被接入，被理解。

我更偏向于开发项目前先约定好并完成一定数量的文档，可以只完成大概框架，文档需要在开发过程中不断进行版本的更新，以保证和项目进度的同步。在项目完成的时候，需要针对项目的文档，也制作一份文档进行梳理和介绍，这样一套软件文档才是完美的。

对于“软件工程文档写作”课程理论与实验教学的建议

理论教学和实验教学只有六周，所以我认为本门课的价值就是在于为我们打开文档写作的大门，让我们心里对文档写作重视起来，把它当回事。我觉得理论课可以给我们在介绍概念的基础上展示一些比较前沿的案例，让我们增长见识，看看那些大厂是怎么规范文档的，还可以多分享一些标准的文档模板，我们下来就可以自己研究写作；实验教学自然是以实践为主，不过可以将要求细化，让我们有目的地写作而不是凭空想象，毕竟大多数学生还是没有实际项目的。

---

以上就是我对于软件文档写作的全部见解。