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.
Mats Broberg reports: <<These softwares are quite complex and consist of
commands and dialog boxes, making up a very deep tree-structure. My view is
that the documentation should provide a description and explanation for each
and every command and option in these dialog boxes.>>
So far, so good. I agree that documentation that skimps on the details isn't
much use to users.
<<I have gotten rid of the deepest levels of headings by arranging the
information in tables (in a sort of InfoMap arrangement), but I still need
about 8 levels of headings. I know what you think, and no, the software that
I am describing can not be designed in a simpler way! :)>>
Fortunately, the headings can be. All you need to do is promote subordinate
levels of heading (e.g., L8) higher in the hierarchy. A simple way to do
this would be to add the subordinate heading to the heading one level above
it. For example:
1.1 Operation of camera 1.1 Menu explanations
1.1.1 Buttons 1.1.1 File menu
1.1.2 Gauges 1.1.2 Edit menu
1.1 Operation of the camera's buttons 1.1 File menu
1.2 Operation of the camera's gauges 1.2 Edit menu
1.3 Operation of the camera's dials
And so on. You can simplify further by turning the L1 headings into
"chapters" rather than numbering them 1., 2., etc. Chapter titles can be
reversed type on a dark background at the top of the page. Sometimes you can
use "bleed tabs" for the same effect; here, the heading comes at the outer
edge of the page, running vertically, and the ink surrounding it runs right
to the edge of the page (it "bleeds" off the page). Users can flip through
the book quickly until they see the appropriate chapter title at the right
margin. Cardboard inserts or full-page chapter titles are another way to
accomplish the same effect. Color can be used to indicate a chapter heading
if you're allowed to use spot color in your manuals. Other possibilities
<<I am using incremental numbering for the headings, due to the fact that I
believe that it is wiser to differentiate deep levels of headings merely by
a number whilst keeping the same typeface and size for these deep levels. By
looking at the number the user can immediately see where he or she is in the
I've never seen a good defence for the use of numbered headings outside of
legislation, military specifications, and the like; in each of these cases,
the documentation is used by experts who use the docs often enough that they
eventually memorize the numbers. Once that's done, the numbers become truly
But for consumer products, I defy you to produce any usability study that
tells me a typical consumer can look at a five-digit number and know what
each number says about where they are in the hierarchy. They simply don't
consult the documentation often enough for this to help. If the hierarchy is
so complex that it requires numbering, it's too complex for the general
public. And for me, for that matter.
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
"Science is built up of facts, as a house is built of stones; but an
accumulation of facts is no more science than a heap of stones is a
house"--Jules Henri Poincaré
Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.