8

We have a tool that we cannot replace that does not support single sourcing. As a result, with instructions that involve the same node, we either repeat the same dozen steps over and over, or refer the user to say chapter 2 sectionXY23 to perform steps 1-17 and then carry out step 2 and 3 from here.

The first alternative is a lot more user friendly but heavy on maintenance. The second solution is really awkward but can be maintained.

Which one is more future-proof? (This tool is here to stay so there is no replacement option.)

migrated from techcomm.stackexchange.com Feb 20 '18 at 15:17

  • 1
    What tool is it. You would be amazed at the things some people figure out to make some tools do what they want. And knowing the tool is essential to answering the part about maintenance. – user16226 Feb 4 '18 at 14:02
  • en.m.wikipedia.org/wiki/TestLink this is the beauty I am talking about. – Lefty G Balogh Feb 4 '18 at 15:26
  • 1
    But that is not a docs tool at all. It does not even mention creating docs as a capability. You would be better off using Word. How are you stuck using a test tool for docs? – user16226 Feb 4 '18 at 15:37
  • Why the -1? This is not a dis/like button. – Lefty G Balogh Feb 4 '18 at 18:14
  • 2
    Roger that. All I am saying is please for each downvote, add a comment or a flag saying why the Q is bad and how it could be improved. – Lefty G Balogh Feb 5 '18 at 8:52
7

This is a close duplicate of Does DRY (Don't Repeat Yourself) Apply to Documentation?

My short answer is do what's right for the user, not yourself. That's probably repeating the code, especially if there's extra or modified steps included. You'll lose the user along the way.

My long answer is that this is a also a good case of writers needing to push back against management. Mark Baker is correct in that TestLink isn't a documentation tool at all. And why is management even pushing it in this role? Writers have a responsibility, even a mandate, to demand the right tools. We're put upon enough as it is. Management isn't requiring developers to use Word as their IDE, even though it can technically do that. If management doesn't see the problem with using the wrong tools, then they have to live with the consequences. In this case, it begins with higher maintenance costs, longer schedule requirements, and high risks with quality standards, as writers have to update the same material in several places.

6

I concur that Does DRY (Don't Repeat Yourself) Apply to Documentation? pretty much answers the question on what is best for the user.

However, the question was:

Which one is more futureproof? (This tool is here to stay so there is no replacement option.)

In your case, as much as I don't want to say this - referring might turn out better in the long run. Here's why:

  1. As time goes by, you'll keep on accumulating duplicate, hard-coded content.
  2. At some point it will become impossible to maintain it, so you'll begin offering outdated or erroneous content to customers.
  3. Your users will not be able to do their job because they'll be getting outdated content.
  4. You'll end up with bad content and unhappy users.

With your particular setup, I'd say that "correct content available through timely and accurate referral" trumps "all the content in the right place at the right time".

  • 2
    I agree with this. Accuracy is arguably more important that user convenience. If the content because inaccurate and inconsistent, it may cause user errors. If the documentation is for a critical system, an error could be very bad. – Scribblemacher Feb 5 '18 at 13:13
3

I think there is one thing to be said on this that is not covered by Does DRY (Don't Repeat Yourself) Apply to Documentation? and that is this:

It is not uncommon that there are common operations that must be performed as part of many different tasks. For instance, you might have to log on to the admin interface before performing dozens of different admin tasks. Lets suppose that logging on to the admin interface is a moderately complicated procedure with four or five steps. Do you put those four or five steps in every task instruction or do you simply write:

  1. Log on to the admin interface (see page 6).

(or make the text of the step a link to the instructions for logging on)

The answer, I believe, depends on the frequency of use. If you are writing for people who will be doing admin tasks frequently, you use the reference format because they will quickly learn how to log on to the admin interface and will not need those instructions each time. Omitting them actually makes most operations faster and easier to understand.

But if you are writing for people who only do admin tasks once in a blue moon, it is better to include the step for logging on in each procedure because people will need them every time and it will be a lot easier for them if they are inline.

  • 1
    This comment isn't specifically about your reply but applies to many of them, but consider that most authoring tools have the concept of the snippet, or reusable text. This may apply here. I like seeing procedures being complete and in sequence, so a snippet may be the best of both worlds here. One place to edit, and appear in many places. – ForEachLoop Feb 5 '18 at 21:58
0

Based on the communications model used in physical engineering and architecture, the correct answer is "refer", whether the data occurs in long technical documents, specifications or in the final construction drawing sets.

a) Accuracy & ease of maintenance.
b) Simplicity & low information duplication.
c) Clarity - enduser has only ONE place to find datum "x", not 12.
d) Clarity - regulatory reviewer has only ONE place to find datum "x", not 12.
e) Be authoritative: say it once, say it right, when in doubt tell 'em to look at it again.

  • My engineers would most certainly love your answer. :D – Lefty G Balogh Feb 6 '18 at 20:09

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.