Post History

Source: https://writers.stackexchange.com/a/33495
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/33495
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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?](https://writing.stackexchange.com/questions/33529/does-dry-dont-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.

Original score: 3