Is it better to repeat steps listed elsewhere in a manual, or to refer the reader to where the steps are listed elsewhere in the manual?
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.)
This post was sourced from https://writers.stackexchange.com/q/33492. It is licensed under CC BY-SA 3.0.
2 answers
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:
- As time goes by, you'll keep on accumulating duplicate, hard-coded content.
- At some point it will become impossible to maintain it, so you'll begin offering outdated or erroneous content to customers.
- Your users will not be able to do their job because they'll be getting outdated content.
- 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".
This post was sourced from https://writers.stackexchange.com/a/33494. It is licensed under CC BY-SA 3.0.
0 comment threads
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:
- 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.
0 comment threads
0 comment threads