您如何描述您的解决方案/系统？

Question

我即将编写一些项目经理、开发人员和业务分析师会使用的标准/指南和模板。目标是更好地理解正在开发或已经开发的解决方案。

其中一部分是提供有关记录解决方案的标准/指南。例如。记录解决/满足业务案例/用户需求的软件。

现在，作为一名程序员，我可以看到不可能说“每个解决方案都必须使用 Y 定义 X 并根据 Z 呈现它。”因为 X Y Z 并不总是适用等等。

但是，我知道，即使对于我的爱好项目，我总是以一种或另一种方式描述我的解决方案，模块/组件、源代码 cmets、API、数据库模型、使用的一些分类法、日志日志、xml 格式等..

因此，为了继续我的工作，如果您能分享您记录的内容以描述您的解决方案（最好还有如何和为什么），我将不胜感激 - 我知道它会因许多事情而有很大差异，但任何一般或具体的答案是有趣的。谢谢。

更新 不清楚，但我不是指 X Y Z 的用户需求。我指的是系统可能拥有的所有可能类型的文档。因此，将其解读为“不可能说明每个解决方案都必须具备：所需框架列表；服务器软件的操作手册；所需的主数据；用户需求与测试的矩阵；用户界面规范。虽然产生如此有限的框架是有意义的。一组需求，很难清晰和准确，因为最重要/最相关的内容因项目而异。

另外，我很久以前就问过这个问题，但从未接受过答案，对此我深表歉意。也许，既然这是一个悬而未决的问题，作为社区 wiki 会更好？

Answer 1

如果您的这个项目能够长期存在，您可能希望开始考虑使用一些行业一致的方法。最后，您可能会花费更多时间，并且可能会得到相同的最终结果。

这还取决于您所谈论的文档级别： 有关基于应用程序的架构指导，请查看Microsoft Application Architecture Guide 2.0（最近发布）。

如果低于此级别，请从 SandCastle 之类的内容开始，然后在逻辑上扩展它产生的内容。

就个人而言，我喜欢从交互图开始，简单地展示系统的所有组件如何相互交互，然后将每个组件分解为类。将类分解为序列图，并继续进行，直到获得方法级别的状态图，或者对您的项目有意义的程度。

如果您需要更高级别，请查看我之前的帖子：Enterprise, Systems and Application Architecture (best Practise)

归根结底，只要它对阅读它的人来说合乎逻辑，并且有用（而不是你只需要交付并且永远不会再次使用的东西），你就做对了.

更大的问题通常是使文档保持最新。这将很快将您带到流程和程序创建/改进任务。

Answer 2

文档始终是任何项目中最棘手的部分。如果您想重新开始，那么您可能需要查看Domain Driven Design。

如果您有正确的模板，使用故事模板会非常有益。

作为一个 [X]
我想要 [Y]
这样 [Z]

您可能想以类似的方式查看Use Cases

Answer 3

使用当前域的单词。如果有一个常用的业务领域词，那么在文档和代码中一致地使用相同的词。如果有一个常用的编程术语（例如众所周知的设计模式），请在编写代码和记录技术细节时使用它。

为了记录程序的工作原理，作为用户界面设计的一部分，我制作了图片序列（在纸上或 powerpoint 上），展示用户将如何使用用户界面执行任务。这是每个人都能理解的通用语言，从用户到客户，从经理到程序员。

Answer 4

基本上有很多方法可以为项目编写文档。我过去使用的 2 种方法是 1) 用例驱动开发，以及 2) 测试驱动开发。由于我只使用过一次测试驱动开发，因此我建议如何使用用例驱动开发。

这里的关键是彻底使用 UML 符号。用户、业务分析师和开发人员（显然）讲不同的语言，而您尝试做的是使您的文档有意义。有 3 个基本文档是关键。

1. 业务规范 - 本文档由用户制作，无需任何干扰或与开发团队协商。为什么？因为这个文档需要纯粹捕捉用户需要的东西。例如，用户想要一个程序来煮咖啡。现在用户的咖啡机必须手动打开。用户的大脑在早上需要时间来运行所有的气缸。

2. 软件需求规范 - 这是分析师将用户需求分解为功能规范的地方。分析师根据用户的需求创建流程。这是您开始使用 UML 的地方。从用例和活动图开始，了解系统的感受。获取其他衍生规范，例如安全要求和其他需求，例如基础设施约束。

3. 软件设计说明 - 这是架构或解决方案设计人员为设计满足要求的解决方案而生成的技术文档。架构师分解功能规范并将流程转换为技术规范。每个用例都可以分解为序列图和通信图。你可以用这些图做的是开始为类创建函数。这些图可用于开发类图。您可能知道状态机分解类图，但我通常不会走那么远。您还可以使用组件结构记录整个架构并在本文档中分解其组件。该文档还可以包括系统将要放入的部署基础架构。

结合使用这 3 个文档可以帮助读者更好地了解系统中的工作原理。程序员可以了解技术规范的来源，以及它们最终需要如何发挥作用。如果您无法让程序员理解技术规范以制作正确的功能，不妨告诉他们最终需要如何运作。

为了与来自不同级别的团队成员（例如，用户、经理、业务分析师、解决方案架构师和程序员）进行协调，我创建了一个矩阵，将业务规范、功能规范和技术/设计规范联系起来。该矩阵还将包括将与要测试的元素相协调的测试模块。矩阵在实现 V-Model 开发方法时非常有价值。

矩阵示例： “业务需求 A”->“功能规格 A”和“功能规格 B” “功能规格 A”->“组件 A”、“组件 B”和“组件 C” “组件 B”->“A 类”和“B 类”

当然，这在电子表格上总是看起来更好。

Answer 5

不幸的是很少！

但是，如果您的指南是针对经理和开发人员的，那么您使用的语言与您展示它的方式一样重要。避免使用流行语和营销术语，(Here's a good list!)

我个人认为图表和绘图有助于强化想法，预期用户与系统交互的流程图可能有助于更好地展示系统应该做什么。 （当然还要深入分析系统是如何实现这一点的！）

Answer 6

为了扩展您的项目的范围，您最好使用领域词进行交流。对于需求发现，prototype tools 可用于快速构建 UI，以确保充分理解需求。如果您的目的是找到记录解决方案的最佳方式，我认为它确实与solution architecture 有关。 我还认为IEEE 1471 标准为记录软件架构提供了一种整体方法。另请查看perspectives and viewpoints 方法。当然，您可以使用您喜欢的 UML 工具来完成。

Answer 7

也许是因为我刚刚读过它，它仍然在我脑海里嗡嗡作响，但我认为它值得一读37signals Getting Real。虽然它是关于启动一个项目，但我（作为一名程序员）对文档的处理方式非常满意。这不符合每个人的口味，但如果其他人都支持这种方法，那么它甚至可能使文档变得愉快。我是这样发现的。

Answer 8

以下是我整理的清单，我认为在描述解决方案时有这些内容是有意义的。我把它变成了一个wiki，所以请加入并挑战和添加。

1. 数据存储库（数据存储在哪里？如何访问？）
2. 数据格式（使用哪些格式？是否有新引入？规范） 规模增长？
3. 配置（可以配置什么，默认什么）
4. 库/框架/包依赖项（供应商、许可证、版本）
5. 构建解决方案（如何获取所有文件等并逐步构建）
6. 模块（定义范围/引入模块的原因）
7. 类/源代码文档（由 Doxygen 或同等工具生成）

还有兴趣： 1. 安全性（解决方案的哪个区域是安全的，密码/加密等） 2.数据传输（磁盘/网络之间传输什么？通过哪些变量来完成

Answer 9

TOGAF（开放组架构框架）定义了架构师应如何定义解决方案的“方法”。 TOGAF 的一部分还涉及定义作为架构项目的一部分应该产生哪些输入和输出。

但是，对于您需要哪些文档在不同的人（BA、程序员、测试人员、经理等）之间共享的问题，您应该查看 TOGAF 中的 Views 和 ViewPoints。你提到的所有这些人都是你的利益相关者，观点和观点解决了利益相关者的担忧。因此，我鼓励您尝试一下 Views 和 ViewPoints。