Re: Difference in writing styles of User Manuals, Online Help, Printed Documentation, etc.

["Michael West" <mbwest -at- bigpond -dot- net -dot- au>]

John Mathew asked:

> Could you please tell me the exact difference between
> a User Manual and a User's Guide?
> 
> What are the differences between Online Help and
> Printed Documentation?
> 
> Do we have to adopt a different approach in writing
> online help, user manuals, and printed documentation?
> 
> Is single-sourcing possible? How best to do that?
> 
> Finally, what are the different documents that are
> normally prepared during the release of a product?


Hi John,

I hope by now you understand that there are
any number of possible "right" answers to these
questions.

The difference between a User Manual and a User's Guide?
Not much. "Guide" suggests to me a procedural focus,
but there's no law that everyone follows in using these titles.

Do we have to adopt a different approach in writing
online help and printed documentation?
Well, there are the obvious things: hyperlinking does not 
apply to print, for example, and therefore the print medium
usually requires additional "meta-text" to help users find their
way around. Beyond those structural features, I have found 
that the same writing style works equally well in print and 
online: tight, concise, modular, well-structured,
top-down, clearly labelled. Some other folks insist that 
online writing must be *more* concise, but for my money, 
concision is just as desirable in printed user guides. The
notable exception is the chatty, discursive style preferred by 
"personality" authors of third-party aftermarket How-To
books. ("Windows Solitaire for Utter Dolts" and the like).

Is single-sourcing possible? Sort of. How best to do that?
Depends. In some tools you can generate printed doc from
help files and in others you can go the other way.
What does "best" mean? I prefer working from Help to print, 
but that's because in our current SDLC the Help is delivered first. 
In another shop, the printed material might be the primary source.

What are the different documents that are normally prepared 
during the release of a product? Depends. What is the
product? What are the needs of the users? What are the needs
of the business? You need to have all that worked out before you 
start. I've noticed that the "standard" package of user documentation 
from the big vendors has been considerably scaled back in recent
years. Whereas in the past a comprehensive user guide was 
considered standard, it is rare now. More commonly a "Getting
Started" type book is packaged with the software. Often,
comprehensive printed guides are extra-cost extras.

This is just one set of possible responses.

--
Michael West
Melbourne, Australia













^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

---
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.