I’m sceptical about how much “jumping around” users do anyway. Users are generally looking for answers. When they find the answer, they tend to stop looking. If I’m right about that, by reducing reuse you could be making your users work harder to find what they’re looking for.

As for the second reason, well, yes, reuse is not free. But the effort needed to make content reusable is pretty much the effort needed to make it useful in the first place. Predominantly, content that cannot be reused is badly written content.

And surely reducing the “bulk” of your deliverables to increase efficiency is today only relevant to printed media.

That said, I agree that the power to reuse content should not be abused. But the danger of excessive reuse is poorly structured and incoherent documentation, not jumpy readers or over-worked authors.

I’ve struggled with the consequences of choice 3, “Remove all but one instance of the content, and if you must, point to it rather than copy it,” in a non-structured environment in which references were made to multiple documents, all of which had to be downloaded for the reader to make use of the references. And the impossibility of keeping duplicated information up-to-date is what attracted most of us to structured re-use in the first place.

In general, I’ve found that the rewards of re-use far exceed the pain of making the content fit multiple contexts. But I agree that we need better guidelines for determining when reuse just isn’t worth the effort. Will this topic be addressed in your forthcoming book on managing writers?

Thanks from the trenches,

Jim

The more fundamental problem, I think, is the refusal to allow time for full, careful review of the text by writers, editors and approvers. How to solve that with the constant mantra of cost-cutting droning in one’s ears is anybody’s guess.

This would result in a hybrid system though, where the author couldn’t modify the content without first ascertaining whether the developer’s aggregation had some stake in that fragment. An arguably more robust approach is to have the author create the information in a way that makes sense for them, then have them confirm that the output produced is fit for purpose.

This should be more productive for the authors and developers as well as providing more predictable outputs.

As a reader, when I come across a chunk of text that I recognise having seen before in a different part of the same documentation set, I am usually a bit taken-aback. Also, being of a distinctly distrustful nature, I usually go back to the other place and check both passages almost word for word, to see if they are the same. This is because I _know_ that duplication happens in technical documentation, and I also know that there’s not guarantee that both occurrences are up to date.

So, as a technical writer, I’ve often suggested that a re-used chunk of content should actually include a statement at the top, telling the reader that this piece of text comes from a library of re-usable chunks.

As you say, there definitely are cases where content re-use is advisable. For example, you may need two versions of an installation guide, for two different technical environments, but where large portions of the guide are the same in both environments. Instead of telling your read to go somewhere for the common instructions, then come back for the special bit, then go back to the common set, etc, you should be able to give them a single set of sequential steps. So the common instructions would be from a re-usable chunk.

Another case is when you need to issue a product warning of some kind, which affects more than one version of the product. If it’s in a re-usable chunk, you can simply empty the content when the warning is no longer required.

A good, thought-provoking article. Thanks!

Your article sparked another thought for me. As I writer, I’m all for structure and efficiency, but as a some-time user of documentation, I have some qualms. On more than one occasion, I had trouble understanding something as it was written in one place in the doc but I did understand a similar passage about the same topic that appeared elsewhere, mainly because a quick in the wording helped clarify something for me. As a reader, I was able to exploit the writing team’s “messy” inconsistency to my benefit.

Likewise, if you don’t understand what someone is saying in casual conversation, you question the speaker. Unless he or she is a robot, the other person usually replies by giving you the same information but with slightly different wording so that you “get it” the second time around. Scrubbing our language of all variation closes that loophole.

Don’t get me wrong. I’m not arguing in favor of thoughtless repetition and variation. I’m just wondering if it might have some cognitive benefit, since it seems to be hard-wired into human communication patterns.