1

在我的项目开发过程中，我发现自己制作了一些大型文档，只有几段略有不同。例如，相同的配置计划将在不同的项目中使用，但每个文档都必须根据特定数据进行定制，并符合某些特定要求。作为一个懒惰的人和模型驱动开发的粉丝，我一直在寻找优化这个过程的方法，我得到了以下选择：

  • 文档模板- 使用带有表单（模型）的主文档模板（演示文稿）或将文档的版本限制为仅几个关键字段，然后交叉引用整个文档中的输入数据就可以了...但我仍然觉得我可以将这两层分离得更多一些。
  • UML 建模- 使用支持 UML 的 CASE 工具，我认为我可以将我的文档建模为带有注释的包和类，更改每个项目的模型并使用文档模板生成报告。问题是这些工具不是为处理大量文本而设计的，我在进步时遇到了一些困难。
  • 流程建模- 使用 Eclipse EPF https://www.eclipse.org/epf/对于我想要完成的任务来说似乎有点矫枉过正。记住：我是个懒人。

我想向社区询问他们在基于模型的文档方面的经验，或者他们在整个软件开发周期中优化文档生成的方法。

4

1 回答 1

0

我不确定我是否完全理解，所以如果这错过了标记，我深表歉意。

我遇到过（我认为）类似的问题，内容与需要呈现的文档之间存在多对多关系。例如，需要包含在需求文档中的“项目概述”，项目计划等

到目前为止，我发现的最佳解决方案是：

  1. 以Markdown格式编写每个部分。有一些不错的编辑器可以让编写 Markdown 变得简单高效（例如OSX 上的Mou）。
  2. 使用Pandoc将 Markdown 转换为重组文本 (RST)。
  3. 使用Sphinx从 RST 文件生成文档。

我有多个 Sphinx 文档模板，每个模板都将一些常见部分与特定于该文档的其他部分结合在一起。如果其中一个常见部分得到更新，则很容易重新生成所有文档以进行合并。版本控制非常简单，因为源文件都是简单的文本。Sphinx 还可以轻松生成多种格式：例如 html 用于在线发布，或 pdf 用于打印/分发。

您可以通过本机编写 RST 来消除对第 2 步的需要。对我来说，额外的步骤是值得的，因为我还没有找到像 Mou 一样舒适或高效的 RST 编辑器。当然是 YMMV。

这不是一个完美的解决方案：例如，跨部分创建链接并不是那么容易。但总的来说，它可以很好地满足我的需求。

hth。

于 2014-02-04T23:20:01.677 回答