Link to home
Start Free TrialLog in
Avatar of Stephen Kairys
Stephen KairysFlag for United States of America

asked on

Tech Writing - Repeat same explanation in 25 similar documents in a wiki.

I have a series of apx  25 documents that describe 25 instances of a configuration screen on which you select - or enter - one or more data elements.. Each screen deals with a different concept (e.g. age, gender, etc).) But they all have common elements (e.g. how to clear all settings, how to display only selected items etc.

I'm leaning toward including these concepts on each of the 25 pages. (Ease of reading for our audience.) But, if, for some reason, our developers change the process of (e.g.) deleting all data elements), they I'd have to change it in 25 places.

I guess I could include these commands on a separate page, and simply say (on the 25 pages), "Click here for global commands."

Thoughts?
Thanks,
Stephen
ASKER CERTIFIED SOLUTION
Avatar of Chinmay Patel
Chinmay Patel
Flag of India image

Link to home
membership
This solution is only available to members.
To access this solution, you must be a member of Experts Exchange.
Start Free Trial
Avatar of Stephen Kairys

ASKER

Thank you for your prompt response.
Follow-up. In addition to the commands which apply to all instances of the configuration screen, there are two related command that (for now apply to only 2 instances of the configuration screen. And would be a distraction to the user he needs info for the majority of the docs.

So I'm thinking have two sections in the overview doc.
-Commands for all screen (every config doc links to it)
-Commands for selected screens (only the 2 docs that need that info link to it).

Does the above sound reasonable in terms of ease of use of the documents?

Thanks.
Absolutely. I regularly write technical documents and they are well received by the clients. One principle that I always follow is, to keep the relevant content in the document. When you add unnecessary stuff to the document it gives an impression that you are trying to increase page count without adding any real value. In my eyes, repetition without any logical reason is euqal to have a blank page after every page.
Thank you. And to take this to another level, I realized the command that is supported only in selected screens is so simple (one or two sentences.)  that it's not even worth forcing the user to go to another page (the overview doc). While I'll still include the info in the overview doc (in detail), I don't believe a link is necessary.

e.g. "To view only selected items, click Selected Items Only"