Re: Which is better for simple online help, more or less nesting, more or fewer hyperlinks?

Subject: Re: Which is better for simple online help, more or less nesting, more or fewer hyperlinks?
From: "Peter Neilson" <neilson -at- windstream -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Mon, 12 Dec 2011 16:57:26 -0500

In general, the mind is unable to maintain a multi-level structure easily. Hence it is generally folly to use even two-level entries in an index, and insane to use three, without putting each third-level entry also at the top level, as in this example:

Finagle
baroque usage
gloops 34, 78, 105 ff
common usage
Gloops (/no such entry in index/)

It requires the person searching for the term "gloop" to know what it is and where to find it before learning about it.

One the other hand, description of certain complicated concepts can occasionally require deep nesting. The topic headings and the table of contents should give the reader clues.

Finagles, historical and recent perspectives, including Gloopism.
Renaissance and Baroque terminology, including Gloops, Blobs and Kumquats
Gloops in Renaissance works
Gloops and Blobs in the Renaissance and later
Baroque introduction of the Kumquat as a replacement for the Gloop
Modern terminology, and rediscovery of the Gloop

It can be particularly difficult to comprehend multiple sections each of which contains identical substructure:

Aaaaa
Wxyz
Wzxy
Wwxy
Xyzzy
Bbbbb
Wxyz
Wzxy
Wwxy
Xyzzy
Ccccc
Wxyz
Wzxy
Wwxy
Xyzzy

Nesting with section and subsection numbers is often a standard, as in military documentation, allowing the construction and maintenance of an immense document by several authors over an extended period of time. Whether the visible numbering scheme ("Sections 4.2.1.7.6a through 4.2.1.8.1c, inclusive") aids the reader remains as an exercise for the student of technical communication. It is unavoidable in the writing of well-constructed laws.

I guess the basic question is whether the written structure is one that inherently exists in the material being described (the lock is part of the latch mechanism, which is part of the door) or imposed only by the writer. Is "Print Preview" part of the interface, or is it rightfully a topic by itself?

On Mon, 12 Dec 2011 15:58:46 -0500, Porrello, Leonard <lporrello -at- illumina -dot- com> wrote:

A colleague and I are both writing online help for various products. I just noticed that while he is using a TOC structure that includes more nesting (and several levels), I am using a TOC structure that is more flat (featuring only two levels). Following are examples of what my TOC structure would look like using each approach. As you are looking, keep in mind that the application is straightforward and that everything at my level 1 (short of "File Types," "Technical Assistance," and "Revision History") appears on the first screen of the GUI. I think more nesting would be called for were I documenting a more complex application or if the online help were more complex or lengthy. Finally, I should also add that I don't prefer one approach over another and would do whatever is best for the user.


My collapsed TOC tree looks like this:

Home
Current and Completed Jobs
Change the Repository
Requeue the Job
Print Preview
Amplicon Jobs
LibracyQC Jobs
Metagenomics Jobs
File Types
Technical Assistance
Revision History


My expanded TOC tree looks like this:

Home
Introduction
Topics
Current and Completed Jobs
Change the Repository
Requeue the Job
Print Preview
Amplicon Jobs
Summary
Sample
LibracyQC Jobs
Summary
Sample
QC
Metagenomics Jobs
Summary Sample
File Types
Type A
Type B
Type C
Technical Assistance
Revision History


Using my colleague's approach, the collapsed TOC would look like this:

Home
About the Interface
Types of Jobs/Workflows
File Types
Technical Assistance
Revision History


Using my colleague's approach, the expanded TOC would look like this:

Home
Introduction
Topics
About the Interface
Current and Completed Jobs
Change the Repository
Requeue the Job
Print Preview
Types of Jobs/Workflows
Amplicon Jobs
Summary
Sample
LibracyQC Jobs
Summary
Sample
QC
Metagenomics Jobs
Summary Sample
File Types
Type A
Type B
Type C
Technical Assistance
Revision History


On a related note, my colleague uses hyperlinks to list children pages on their respective parent pages. I do not link to child pages from parent pages as the TOC is simple. Because the TOC is simple, I would argue that adding hyperlinks from parent pages to child pages is unnecessary. These links merely duplicate what the user can see in a moment in the TOC, which is immediately adjacent to the page. The additional links are nice in terms of "bling," but they increase writing costs and arguably add little to nothing to usability.

Please let me know what you think.

Thanks!

Leonard


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as neilson -at- windstream -dot- net -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/neilson%40windstream.net


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
Re: How/where would you handle this documentation problem? (david hendler): From: Chris Despopoulos
Which is better for simple online help, more or less nesting, more or fewer hyperlinks?: From: Porrello, Leonard

Previous by Author: Re: need suggestions on handling a boss
Next by Author: Re: Document Standards
Previous by Thread: Which is better for simple online help, more or less nesting, more or fewer hyperlinks?
Next by Thread: Re: Which is better for simple online help, more or less nesting, moreor fewer hyperlinks?


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads