文档工具是如何让开发团队失败的

绝大多数软件开发团队都对自己的开发过程感到不满。我认为其中 50% 的问题可以追溯到糟糕的文档管理工具。本博客讨论了软件项目的文档管理工具的现状，并提出了一些改进的设想。

95% 的软件项目使用 Microsoft Word 来管理文档，有时会辅以 SharePoint。这个系统的问题在于：

1. 速度太慢。
2. 很难找到哪些内容被修改了，是谁修改的，以及何时修改的。
3. 很难将当前版本与先前版本进行比较。
4. 很难将文档的一部分隔离出来作为硬性需求，使其与背景信息区分开。
5. 粒度太大，无法对单个需求进行版本控制。
6. 处理单个主题、章节或分支很困难。
7. 很难将文档的一部分或几部分通过电子邮件发送给某人。
8. 登录后很难快速了解自上次登录以来发生了哪些更改。
9. 很难知道自己已经评审过哪些内容，哪些尚未评审。
10. 在根据需求编写代码时，很难勾选已完成和未完成的工作。
11. 无法针对需求签入代码。
12. 创建一篇新的、小的文档，例如扩展用户故事，需要花费太长时间。
13. 多人协作编辑同一份文档是一场噩梦，即使它能正常工作。
14. 文档的一个元素（如需求、用户故事、用例、实现细节等）作为一个具有生命周期和独立工作流程的实体，并且独立于其所在文档的工作流程的概念，是不存在的，也无法创建。
15. ...

好吧，这已经超过了十几个问题，而且我只花了大约 5 分钟就想到了它们。我相信在这篇博客写完之前，我还能想到另外十几个。

现在，想象一下如果我们以写文档的方式来写代码。只把所有的代码写在五六个巨大的文档里，然后把它们放在一个大的 SharePoint 网站上。我需要详细说明这些问题吗？不需要。显而易见，以这种方式处理代码将是完全荒谬和不可行的。它会导致噩梦、崩溃和对过程错误进行无休止的分析。它会催生无休止的“专家”浪潮，他们的工作是告诉你工具是次要的，问题不在于工具，而在于过程。我们需要更好地沟通。我们需要更频繁地开会。或者，也许专家们会告诉我们，我们需要更正式的代码签批方法，因为显然你不能在代码写完后未经变更单就修改代码。

听起来很熟悉？

是的，这正是我们多年来听到的关于文档的说法。

好吧，我认为这是胡说八道，我认为是时候让编写文档管理工具的人们醒醒了，并为我们提供真正有效的工具。

现在，我不敢说我拥有所有答案，但以下是一些我认为软件项目文档管理工具应该具备的功能：

1. 允许用户以类似于 Microsoft Word 的方式进行编辑，并创建看起来与 Microsoft Word 相似的文档。不要让用户学习全新的写作方式。这就是为什么人们会回头使用 Word，因为文档工具的开发者们不断违反这个最基本的原则。
2. 当用户写作时，按主题、按段落跟踪正在编写的内容，并**在这些级别上进行版本控制**。
3. 使一个用户能够在三秒钟内创建新文档。
4. 创建大量小文档的难易程度应与创建少数大文档的难易程度相同。
5. 将项目文档组织成一个嵌套的树状结构，所有的小文档都可以作为大树的一部分被集中找到。
6. 让用户轻松创建新页面并开始输入新文档。让用户能够输入新想法所需的时间应约为 2 秒。不能再多了。
7. 允许按主题和段落轻松地重新排列文档。允许我向上、向下移动段落，进行缩进等。
8. 允许用户在一个集中的列表中查看自上次登录以来所有其他作者所做的所有更改。如果用户单击列表中的一项，他将立即被带到文档工具中进行更改的地方，并且更改的段落旁边会显示上一版本的段落，并高亮显示更改的文本。
9. 当用户评审更改时，跟踪已评审和未评审的内容。每个用户都应能立即知道其他人所做的、但自己尚未评审的更改。任何做出更改的人都应能立即知道哪些人已评审过这些更改，哪些人尚未评审。
10. 允许用户通过快速按键（如 Alt-L、Alt-N 等）以及使用简单的按钮行，快速轻松地将文档段落样式从普通更改为项目符号、编号、标题 1 和标题 2。不要创建比绝对必要更多的样式。不要让用户考虑如何应用样式。不要让用户猜测如何进行缩进列表编号。
11. 拥有一个包含项目所有文档的主文档树。对该树进行即时搜索。您键入一个字母或短语，**树会即时**压缩以反映搜索结果，就像 Outlook 最终工作的方式一样，而不是像早期 Outlook 版本那样笨拙、缓慢且几乎无用的电子邮件搜索。
12. 能够将文档节点附加到多种项目工件类型，并让系统智能地识别正在附加的文档节点类型，并将其放置在主树中。例如，BA 创建了一个用户故事。很好。现在 BA 想将故事分解成更详细的内容，例如一个用例、一些更详细的需求，以及可能的实现建议。BA 只需在用户故事下方单击，就会出现一个新的文档窗口，准备好在左侧创建主题，在右侧输入详细信息。可能会出现一个模板。BA 输入一些细节并保存。稍后，在主文档树的“用户故事”部分下，该文档节点及其详细信息将出现。但是，BA 输入的实现细节也会出现在主文档的“实现”部分。而 BA 输入的用例将出现在“用例”部分。
13. 允许将任何段落标记为硬性要求。只需单击一个按钮或按一个快捷键，字体就会改变，旁边会出现一个图标，这时就清楚这项工作必须完成。
14. 现在，所有硬性要求都应该能够轻松地作为列表查看。
15. 当开发人员处理并完成一项需求时，允许将代码签入以响应该需求。或者允许对该需求进行扩展，就像前面提到的用户故事一样。只需单击该需求并编写一些任务、实现细节等。现在，开发人员可以针对各个任务签入代码。
16. 即时显示哪些需求已实现，哪些尚未实现。
17. 能够显示任何段落的版本历史记录。
18. 能够显示整个文档的任何先前版本。例如，让我们看看一个月前的文档是什么样子的。是的，在这里。当时有 112 项需求。现在有 134 项。让我们看看它们在哪里：单击，单击，单击。让我们看看是谁写的。是的，那是客户，那是开发人员，那是 BA。让我们看看上个月发生了哪些变化。好的，单击，单击。这太多了。让我们只看对需求的更改。好的。单击，单击。一切都是即时的。
19. 能够将任何文档部分导出为模板。
20. 让文档附加到项目，并与项目一起备份和恢复，就像源代码一样。如果用户切换项目，他也会切换文档。
21. 随着时间的推移，开始构建文档静态分析工具，检查文档中的明显缺陷并提出更好的方法。
22. 随着时间的推移，开始构建工作流功能，认识到文档元素（段落）作为具有自身生命周期的实体的重要性。

这些功能中的大多数今天都可以通过源代码实现。我发现我们无法对文档做同样的事情是完全不可接受的。

这件事在我脑海里已经考虑了很长时间。近年来，在我工作的公司，我们一直在大力试验将文档跟踪到段落级别的概念，其中每个段落都是 Team Foundation Server 中的一个 WorkItem。通过利用 TFS 中版本控制和链接工作项的能力，我们可以比从头开始开发更容易地获得很多底层功能。此外，我们可以将文档链接到 TFS 中的其他工作项，从而实现我上面提到的用户故事示例等场景。我们希望在 10 月底提供一个可供下载的概念验证，并将欢迎反馈、测试用户和项目贡献者。

如果它被开发出来并且有效，将有一个免费版本。