技术写作的版本控制

Question

我在不同地方寻找答案，包括在这里，但无济于事，或者由于我缺乏版本控制经验而无法看到答案（请原谅我的无知）。

我在一个科技作者团队中工作，我们正在处理的文档包含典型的可重用部分（例如，描述在多个应用程序中使用的GUI元素）。当这样的GUI元素更新为更新版本并且更改影响多个文档时，会出现问题。有没有办法根据组成部分自动检查所有文件，看看文件是否与上述组成部分有关？

Answer 1

您所描述的并不是我认为的版本控制问题。

通过类比，如果程序使用算法并且算法更新，我们不会使用版本控制来检测使用该算法的所有场所是否是最新的。相反，我们使用DRY（不要重复自己）等原则 - 以及促进这些原则的工具 - 来构建软件。

如果您可以在允许您执行链接图像（而不是嵌入图像）之类的环境中创建软件，那可能会有所帮助。顺便提一下，提供此类功能的良好文档管理软件包也可能具有更适合技术文档需求的版本控制功能，而不是git提供的功能。

Answer 2

我明白为什么你会考虑“版本控制”，但我同意另一个答案，这不是版本控制问题。

我认为您正在寻找通常称为“包含功能”的东西：您有N个文档引用相同的GUI元素：您不会重复N次与GUI相关的更改，而只会进行更改一次，N个文档将“包含”描述GUI的文档。

例如，asciidoctor，一个轻量级但功能强大的文档标记系统，有这个概念。 （许多其他系统都具备此功能）。

有关示例，请参阅此blog post;它指的是包含部分代码，但相同的概念可用于包含部分文本和图像。

有关详细信息，请参阅http://asciidoctor.org。