Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

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?

+0
−0

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.)

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/33492. It is licensed under CC BY-SA 3.0.

0 comment threads

2 answers

You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.

+1
−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? 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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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".

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/33494. It is licensed under CC BY-SA 3.0.

0 comment threads

Sign up to answer this question »