简体繁体 English

技术写作的版本控制

[英]Version control for tech writing

原文 2017-05-16 17:19:36 8 2 git/ version-control/ mercurial/ tortoisesvn

I've looked for an answer in different places including here, but to no avail, or maybe I just can't see the answer due to my lack of experience with version control (excuse my ignorance). 我一直在包括此处在内的其他地方寻找答案，但无济于事，或者由于我缺乏版本控制经验而无法看到答案（对不起，请问无知）。

I'm working in a team of techwriters, and the documents we are working on consist of typical reusable parts (eg, describing a GUI element that is used in more than one application). 我正在一个技术作家团队中工作，我们正在处理的文档由典型的可重用部分组成（例如，描述在多个应用程序中使用的GUI元素）。 The problem arises when such a GUI element is updated to a newer version and the change affects multiple documents. 当这样的GUI元素更新到较新的版本并且更改影响多个文档时，就会出现问题。 Is there a way to automatically check all the documents against the set of constituent parts to see if the documents are up-to-date with regard to the said constituent parts? 有没有一种方法可以根据一组组成部分自动检查所有文档，以查看有关这些组成部分的文档是否是最新的？

2 个解决方案

What you describe is not what I would consider a version control issue. 您所描述的不是我认为的版本控制问题。

By analogy, if a program uses an algorithm and the algorithm is updated, we don't use version control to detect if all places using the algorithm are up to date. 以此类推，如果程序使用算法并且算法已更新，则我们不使用版本控制来检测使用该算法的所有场所是否都是最新的。 Instead we use principles like DRY (Don't Repeat Yourself) - and tools that facilitate those principles - to build the software. 取而代之的是，我们使用DRY（不要重复自己）等原理以及促进这些原理的工具来构建软件。

If you can create your software in an environment that lets you do things like link images (rather than embed them), that might help. 如果您可以在允许您执行链接图像（而不是嵌入图像）之类的环境中创建软件，则可能会有所帮助。 Incidentally, a good document management package that provides for this kind of thing might also have version control functionality more suitable for tech documentation needs than what git would provide. 顺便说一句，一个提供了这种功能的好的文档管理包可能也具有比git提供的版本控制功能更适合技术文档需求的版本控制功能。

I see why you think about "version control", but I agree with the other answer, this is not a version control issue. 我知道您为什么要考虑“版本控制”，但是我同意其他答案，这不是版本控制问题。

I think that you are looking for something that is normally called "include capability": you have N documents that refer to the same GUI element: instead of repeating N times the changes related to the GUI, you would do the change only once, and the N documents would "include" the document that describes the GUI. 我认为您正在寻找通常被称为“包含功能”的东西：您有N个文档引用相同的GUI元素：与其重复N次与该GUI相关的更改，您只需进行一次更改，然后N个文档将“包括”描述GUI的文档。

For example, asciidoctor, a lightweight but powerful document markup system has this notion of include. 例如，asciidoctor是一种轻量级但功能强大的文档标记系统，具有包含这一概念。 (Many other system have this capability). （许多其他系统都具有此功能）。

See this blog post for an example; 有关示例，请参见此博客文章。 it refers to including parts of code but the same concept can be used for including parts of text and images. 它指的是包括部分代码，但是相同的概念可以用于包括部分文本和图像。

See http://asciidoctor.org for more information. 有关更多信息，请参见http://asciidoctor.org 。