Writing instructions in multiple contexts - two logical problems

Factual Questions
1

I’m documenting a hardware and software system and have spent much time fighting with two problems.

The first problem is that we need different kinds of documentation but their content partly overlaps. Propagating content change through the multiple kinds is very time consuming and error prone. Are their tools for generating multiple kinds of documentation with partially shared and partially separate content? For example, I have “Detailed Descriptions” available in the programming environment, that show a “Context Help” box to my users when they point at a software control or display. I also have a Microsoft Word document called the “User Manual” that explains everything, including how these controls and displays work. Users might have a paper copy or might open a .pdf document that Word can create (it’s actually some fake printer that generates a .pdf in our corporate IT world). All of these things should have the same technical information about what the “Set Pressure” control does, but the one in the context help system should say “Click on this to read more about pressures”, and the one in the pdf might have a link in the word “pressures” and the paper one can’t have any of those. I wind up thinking each one through separately and trying to remember all the tangents I haven’t run down yet.

The second problem is in naming things. There is multiple tier organization to things. The name a thing gets should depend on where it is. For example, on a jet with four engines, the controls and displays for an engine don’t need full names like “Engine 3 Intake Temperature” if they are already grouped in blocks labeled “Engine 1”, Engine 2" etc. The logical extreme of all this would be perhaps 50 displays that are all labeled and named “Temperature” but all in separate groups and subgroups so it is clear which temperature is meant. But there are other constraints based on whether the software has them similarly organized or needs unique labels, and so forth.

My questions:

Are there names for these problems? It is, for instance, much easier to think through an “off by one” problem if you know that is the name people give it so you can web search it - if these problems have names it’d be great!

Are there tools that manage these?

Are there strategies, tactics, or words of wisdom you can share?

2

I’ll start by saying that your issues are much more involved and complex than anything I’ve dealt with personally – so I feel the need to disclaim that I don’t really have any answers. But it sounds like you’d welcome just about any input, and you’ve captured my attention.

My first thought was, “Huh. Sounds like stuff I’ve done in LaTeX (using the \include directive).” Then I kept reading, and thought it was way more than I’d want to handle in manually constructed TeX, and thought of doxygen. However, being geared very much towards source code, I don’t know if that’s really suitable for your purposes, or that it’s powerful enough. Then I saw your reference to Word and thought, “Uh, oh…no way. Not Word. That way lies madness, and I want no part of it.” :smiley:

Nevertheless, I googled “conditional documentation”, figuring that was the crux of your issue – once you have a tool with that capability, tailoring output with different formats and/or content is just a matter of planning/organization. I did get one hit I found interesting, that seems to be a fairly broad discussion – an archived thread from Joel on Software titled Conditional documentation creator?. It dates back to 2006, but perhaps you can find some nuggets in there.

Then I googled “documentation generator” and ended up at Wikipedia’s Comparison of documentation generators page. At which point I got intimidated by the number of software packages and various options available and decided to post something before I got back to work. (Note that the Other Features section looks like it might be a good place to pick up some jargon for further searching).

Oh, one other thing: something that falls under the rubric of “content management system” (CMS) might be what you want. But this is all beyond my personal experience, so I’m just throwing it out there…again, it’s not that I have any great insights here or have looked into anything you couldn’t find on your own, but if any of the poking around that I did helps you at all, that’s great.