Tech Writing - Repeat same explanation in three related section of document?
Hi,
I'm documenting a connected series of screens that contains list of geographic locations. There are three screens;
Each geographic entity can be assigned a value. e.g.
The returned value is the one for the most specific entity:]
Would it be better practice to repeat the above derivation of the returned value in each section (3 instances) or just once (in the intro). My concern is that if I put it in the intro, and someone is reading only the State section, they'd miss out on this explanation.
What you do think?
Thanks,
Steve
I'm documenting a connected series of screens that contains list of geographic locations. There are three screens;
- Continent
- Country
- State
Each geographic entity can be assigned a value. e.g.
- North America = 3
- USA = 6
- Ohio = 4
The returned value is the one for the most specific entity:]
- If you are in Ohio: 4
- If you are in the USA but not in Ohio: 6
- If you are in North America but not in USA: 3
Would it be better practice to repeat the above derivation of the returned value in each section (3 instances) or just once (in the intro). My concern is that if I put it in the intro, and someone is reading only the State section, they'd miss out on this explanation.
What you do think?
Thanks,
Steve
Last Comment
n2fc
You never go wrong writing for the least attentive reader! Better to be a tad redundant than have an inattentive reader miss the boat entirely!
ASKER
Thank you. I'm probably going to do that way. My only concern is maintainability - if I change one of the instances, i have to remember to change the others.
I guess another option would be to have a separate section containing this rule, with links to it in each of the three sections?
I guess another option would be to have a separate section containing this rule, with links to it in each of the three sections?
I agree with n2fc above. If I go to the middle of an article for a specific issue I would have to look back if not repeated .
No harm in being redundant in moderation
No harm in being redundant in moderation
ASKER
@John, so you don't like my idea of having a hyperlink to the "formula" in each of the 3 sections? Thanks.
I think I was agreeing with you to have these links
When you say "Would it be better practice to repeat the above derivation of the returned value in each section (3 instances) "
This is what I agree with. Just putting it once in the introduction means I have to look back if I start (for some reason) in the middle.
When you say "I guess another option would be to have a separate section containing this rule, with links to it in each of the three sections?"
I am not highly keen on this latter approach. Just my two cents here.
This is what I agree with. Just putting it once in the introduction means I have to look back if I start (for some reason) in the middle.
When you say "I guess another option would be to have a separate section containing this rule, with links to it in each of the three sections?"
I am not highly keen on this latter approach. Just my two cents here.
ASKER
I'm in favor of duplicating the content. One reason is that we may be moving these docs to Confluence, which has some odd behavior regarding anchor links.
That said, I'm still a little wary about having the same content 3x b/c six months down the road , it may have to be changed, and if I"m not the one doing the changes, the other writer would not know to change it 3x. Thoughts?
That said, I'm still a little wary about having the same content 3x b/c six months down the road , it may have to be changed, and if I"m not the one doing the changes, the other writer would not know to change it 3x. Thoughts?
You may need to talk to the other writer. Our comments above were designed to help the reader. To do it to ease the load on the writer does not necessarily make for easy, unambiguous reading.
ASKER
I hear you. But at this point it's unknown who might be working on this project in the future. And, it's not so much easing the load on the other writer (or even myself) but general concerns about maintainability.
You cannot, as I see it, do it both ways, so you need to decide and I suggest ease for the reader
ASKER
I'll sleep on it and get back to you tomorrow. Thanks.
ASKER
Hi all,
I just sp/w my manager. He wants the explanation only once, with a hyperlink in each section that refers to it.
So, who do I assign points to? Neither of you explicitly endorsed hyperlinks. :)
I just sp/w my manager. He wants the explanation only once, with a hyperlink in each section that refers to it.
So, who do I assign points to? Neither of you explicitly endorsed hyperlinks. :)
It is up to you how you assign points.
ASKER
Is there a way to mark my own comment as a helpful comment (But not the solution). we used to be able to do that with assisted answers
Just mark your solution as your solution
ASKER
No way to mark one's own comment as a solution. Unless you want to post it as yours with both options mentioned:
1. Replicate the actual content 3x.
2. Have hyperlinks to the once instance of the content.
I wish EE would avoid making things more difficult for us to do things...
1. Replicate the actual content 3x.
2. Have hyperlinks to the once instance of the content.
I wish EE would avoid making things more difficult for us to do things...
You need a member of the EE Elite Community to help. I am not allowed to assist in assigning points. But lots of persons accept their own solutions. Press Request Attention above. Sorry that I cannot assist you.
ASKER
Oh, just discovered this. on the WRITE A COMMENT screen, there's a link for "I found my own solution"
ASKER CERTIFIED SOLUTION
THIS SOLUTION IS ONLY AVAILABLE TO MEMBERS.
View this solution by signing up for a free trial.
Members can start a 7-Day free trial and enjoy unlimited access to the platform.
Web Applications
Web applications are systems that run in browsers that perform functions normally associated with other client-based programs. One of the most commonly used web applications is email; instead of downloading individual emails to a local machine, the data is shown through a website. Other examples of web applications are collaborative systems like a wiki or an online game.
15K
Questions
--
Followers
--
Top Experts
Get a personalized solution from industry experts
TRUSTED BY
