Best practice for technical documentation page length on a website?

[Geoff Hart <ghart -at- videotron -dot- ca>]

procrastiwriter (you must hate your parents!) wrote: <<Within the  
original CHM files, the tendency was to have a fairly 'deep' table of  
contents and often lots of relatively short pages within each  
section. This same structure was transferred to the website.>>

The problem with this approach is that it tends to reflect software  
features rather than tasks. To commit jargon, it's too "atomic" (fine  
grained). As you note:

<<Understandably, some people are complaining that it takes too long  
to drill down and find information, and I agree that many of the  
sections could be combined into a single page (many pages are no more  
than a paragraph long). I'm comfortable with this, but in the back of  
my mind I have the words of a web developer ringing in my ears from  
years ago - "web users don't like scrolling, pages should be short  
and snappy".>>

Distrust authority. Even me. <g>

The answer, of course, is that you can combine the relevant text into  
a single page and still largely eliminate scrolling using a simple  
trick that doesn't even require you to use frames: Start all long,  
multi-heading pages with a table of contents (TOC) that links to each  
heading, then hyperlink each entry in the TOC to the appropriate  
heading. For extra bonus points (in case your audiene never learned  
to use the "back" button or keyboard shortcut in their Web or Help  
browser), add a "Return to the top of this page" link at the end of  
each section. No scrolling required -- just a single click to get to  
the heading, and another click to return.

When I do this kind of thing, I always add a simple statement before  
the TOC to clue in the readers to what I'm doing: "This Web page  
contains the following topics:" This statement, combined with the  
underlinged text for each heading, clearly says two things: you can  
click in the following list to go to these topics, and you won't be  
leaving the current page. The latter is important: it's easy to get  
hopelessly lost following an endless chain of clickable links, and  
stating explicitly that this ain't gonna happen is tremendously  
reassuring to some users.

You can also adapt this technique for "meta-tasks": tasks made up of  
many subtasks. The difference is slight. The first page contains a  
list of the steps required to perform a procedure -- kinda like the  
TOC I just described, but for the steps in a procedure rather than  
for the entire chunk of the help system. If the reader only needs a  
reminder of the sequence of steps, they have it right before them in  
a single screen! But if they need to learn the details for any step,  
all they need to do is click that step to link directly to the  
relevant topic that presents the details. I prefer to open this topic  
in a secondary window so that the original window (the steps in the  
sequence) never vanishes. (I try to design so that no more than two  
windows are open simultaneously because some readers object to  
spawning an endless stream of open windows. Readers can still force  
more windows to open if so desired in most browsers using the "open  
link in a new window" command.)

In addition, because the links that have been followed will be  
highlighted by a color change, this provides a kind of checklist  
approach to the amount of progress that has been made in following  
the overall procedure: links that have already been followed change  
color, and the steps that have not yet been accomplished remain in  
the original link color. That can be very helpful too!

You can combine these approaches, so that a single long page contains  
links to a series of procedures; each procedure consists of a series  
of steps that each links to a new open window that provides the  
details for that step. This gets a bit complicated, but with a lot of  
planning, it can be very effective.

Please note: I in now way assert that this approach is a "best  
practice". It makes good logical sense, but logic often meets a  
sticky fate when exposed to real users. <g> However, I've used it  
successfully in several previous help projects and in online  
newsletters with not a single complaint and with an occasional  
heartfelt compliment. But if you're going to unleash this on your own  
audience, be sure to test it to ensure that they like the approach  
and can use it effectively.


----------------------------------------------------
-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
www.geoff-hart.com
--------------------------------------------------
***Now available***  _Effective onscreen editing_
(http://www.geoff-hart.com/home/onscreen-book.htm)


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

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.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-unsubscribe -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.techwr-l.com/ for more resources and info.