TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Which is better for simple online help, more or less nesting, more or fewer hyperlinks?
Subject:Which is better for simple online help, more or less nesting, more or fewer hyperlinks? From:"Porrello, Leonard" <lporrello -at- illumina -dot- com> To:"techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Mon, 12 Dec 2011 20:58:46 +0000
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.
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-
