5、软件开发文档与需求撰写指南

软件开发文档与需求撰写指南

1. 避免无用文档

创建文档需要投入时间和精力。在有期限和资源限制的情况下，那些被认为无用的文档很可能写得很差，并且无法及时更新，最终真的变得毫无用处。

1.1 让文档变得有用

为了使文档有用，可遵循以下规则：
- 结构和范围明确 ：文档应服务于明确的目的，并按照项目或组织内相对标准的模板进行格式化。例如，需求文档应具有明确的目的、范围和风格。无结构、无组织的文档用处不大。
- 指定保管人 ：没有负责人的文档，随着情况变化将无法及时更新，很快就会变得无用。
- 进行评审 ：同行评审是确保文档高质量和有用性的最佳方式。如果文档不值得评审，那么它就没有保留的必要。
- 明确使用者 ：只有有人阅读，文档才有用。如果不清楚谁会阅读某份文档，就很难说它值得保留。
- 融入开发过程 ：事后生成的文档对开发团队来说用处不大。先编写代码再补充设计文档的做法是错误的，创建文档的目的是在设计过程中提供帮助。
- 与其他文档关联 ：大多数文档在设计过程中相互关联，它们从一个文档获取信息，并为另一个文档提供信息。文档应与其他文档建立关联，以明确其在整体设计中的位置，并确保信息的一致性。
- 简洁明了 ：与代码一样，文档的创建、优化和维护都需要付出努力。简短、简洁的文档比冗长、组织混乱的文档更有用、更高效。

如果文档看起来无