文档存储的最佳实践＆amp;组织？

Question

我的任务是提出文档组织的基本指南。目前，我的公司使用Wiki和随机文档的混合，这些文档位于共享网络文件夹中，或者签入源代码仓库。我知道一种尺寸可能不适合所有尺寸，但有哪些最佳做法？我假设某些文档属于源代码，有些属于自己的属性，但这就是我要在这里找到的。这是我们得到的：

• 要求
• 研究文档（例如，测试结果显示我们需要优化现有应用程序，或添加功能）
• 架构/设计
• 技术
• 配置/部署
• 最终用户

另外：

• 功能/演示（销售）
• 供应商文档（例如我们的托管服务提供商）

此外 - 文件是按项目（应用程序）还是按类型（要求与最终用户）进行组织的？

谢谢

Answer 1

文档是被低估的工作

根据公司规模的不同，让经验丰富的软件工程师完成这类工作可能风险较小。我真的不是要冒犯你，但我怀疑你不是一个人。

区分开发和维护非常重要。我将开发定义为瀑布或迭代过程，其中产品被分析，概念化/设计，实现和测试。另一方面，我会将维护描述为开发后的生命，并将一组修改请求（门票）描述为可以分类，优先级并在有限的时间范围内完成，通常为5天。

我认为第一步是评估贵公司当前的开发和维护流程（这不是一件容易的事）。之后，定义本地标准或查看ISO标准非常重要。值得注意的是，ISO标准更有可能告诉您该做什么而不是如何做。因此，经验丰富的软件工程师的重要性。

我认为您应该在集中式系统（如公司内部网站点）中按软件项目组织文档。

以下是有限的文档类型列表：

<强>分析

• 用例
• 域名模型
• 系统序列图

<强>设计

• UML图表（类，序列，通信等）
• 接口线框/设计
• 数据库关系

Answer 2

不要忘记与客户密切合作，找出他们想要的东西。它们通常决定规格。阿莱蒂也击中了所有的位置。

另外，查看伯克利的软件工程课程讲座。他们介绍了文档：http://inst.eecs.berkeley.edu/~cs169/sp10/lib/exe/fetch.php?media=lecture04.pdf

Answer 3

您将获得关于如何构建层次结构的一系列不同答案，因为正如您指出答案主要是“它取决于”。这取决于目标受众，文档目的等等。

一个不可变的答案是“某处有版本控制”。文档肯定会随着时间而改变（或者你做得不对）。能够追溯事情的变化非常重要。对于那些与特定项目紧密结合的文档，保持工件接近代码是有帮助的 - 项目根目录下的/ docs文件夹不是一个糟糕的选择。你提到“.. 或检查到源代码仓库” - 这很有效，就像sharepoint，wiki或任何其他可以跟踪变化的结构化格式一样。

关于“配置/部署”文档的附注 - 努力实现100％脚本化部署是个好主意，在这种情况下，源代码旁边的/ deploy文件夹是最好的文档。所有