Version control for tech writing

Question

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). The problem arises when such a GUI element is updated to a newer version and the change affects multiple documents. 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?

Answer 1

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.

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.

Answer 2

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.

For example, asciidoctor, a lightweight but powerful document markup system has this notion of include. (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.