Online/print, task/reference, ...

[Stuart Burnfield <slb -at- FS -dot- COM -dot- AU>]

This request appeared on the framers list, but as it's a bread-and-
butter issue for many tech writers I suggested to Thomas that I post
it here and let the techwhirlers have a crack at it.

This issue has come up in a general way before, but there's enough
detail here to make it a nice 'worked example' with which to explore
the question.

Please cc: Thomas with your replies: tmi -at- telelogic -dot- se

Stuart Burnfield


------- Forwarded Message

Date: Sun, 21 Sep 1997 18:02:06 +0200 (MET DST)
From: Thomas Michanek <tmi -at- telelogic -dot- se>
To: FrameMaker user forum <framers -at- FrameUsers -dot- com>
Subject: Online/print, task/reference, ...

Fellow Framers,

Online documentation vs printed manuals, different templates,
task-oriented vs reference material...
That's the topic of this simple post :-)

First a little background:
^^^^^^^^^^^^^^^^^^^^^^^^^^
We develop a set of complex software tools in the CASE domain,
for both the Unix and Windows platforms.
The users are experienced computer users, often engineers.

Our documentation consists of a set of user manuals for different
purposes: installation, tutorials, methodology, reference, etc.
The total page count is over 5,000 pages. Of course, all of it is
made by using FrameMaker. We have a giant book file with 200 files.

The more easy-to-read material (1,500 p) is delivered as printed books.
The reference material is available in printed form at an extra cost.
All documentation is also delivered as online help, currently in Frame
hypertext and HTML, following the same structure as the printed books.

When requesting context-sensitive help from the software (Help menu,
Help buttons in dialogs, etc), a document is opened on-screen at a
suitable page. From each such document, you can reach all manuals,
table of contents, index, etc. That is, online equals print.

Our problems:
^^^^^^^^^^^^^
The documentation is too large, both physically and in file size.
The Frame template is suited for print, not for online viewing.
We have too much "reference" material oriented after tools, windows,
menus, buttons, etc. and too little "guideline" material, oriented
after tasks and work flow when using the tools.

My questions:
^^^^^^^^^^^^^
I'm thinking of remaking the main User's Manual into separated task-
oriented material and pure reference material. The reference material
on windows, menus, etc. should become less volumious than today. The
context-sensitive help should go to the reference material only.

- Do you have any experiencies from such a work? How do you separate
  the two types of material without duplicating information? Can you
  keep them separated but in the same chapter, one for each tool?

- Is it a good idea to let the online help requests end up in a shorter
  reference, or do users want to come straight to task-oriented text?

- Should the reference material be made with a different online
  template, less suitable for print, and the guideline material perhaps
  only be available in print?

We have not yet made any major survey amongst our users. I'm aware of
that these questions depend highly on our specific situation, but do
you have any general advice? Perhaps a good book on the subject, or
a report/study available on the Internet?

BTW, I've looked at the FrameMaker documentation, but I generally find
that the online reference contains too little detailed information
about a specific window/feature, and that it's difficult to find a
specific feature described fully in the printed manual. That's why I'm
hesitant in splitting the information without having to duplicate the
details.

Thanks for any guidelines,

,-------  Thomas Michanek  -----------.-----------  Telelogic AB  ----.
| TITLE:  Documentation Manager        \  ADDRESS:  Teknikringen 9    |
| EMAIL:  Thomas -dot- Michanek -at- telelogic -dot- se  \ (Sweden)  S-58330 Linkoping |
| WWW 1:  http://www.telelogic.se        \  PHONE:  +46 13 200656     |
| WWW 2:  http://hem1.passagen.se/framers \   FAX:  +46 13 212166     |
`------------------------------------------`--------------------------'

------- End of Forwarded Message

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html