RE: Would like your opinion...(Reference to Related Documentation)

Subject: RE: Would like your opinion...(Reference to Related Documentation)
From: "Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>
To: "SB " <sylvia -dot- braunstein -at- gmail -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 21 Aug 2007 13:37:27 -0600

SB quoted an exchange between herself and A (boy, we're saving
keystrokes today!<g>):

> S >> If you need to reference, you should say, refer to the
> Switch User Manual listed under Section ...
> [A] I think that sounds too long winded. I like "...refer to
> Switch User Manual [1]". This is a standard form. If the
> reader doesn't know what that means he has not read many
> academic works in his life, IMO.

To which I'd reply: Is this an academic work? Is our audience made up of
professors and grad students? Even if some of the readers have read many
academic works, would they expect to see academic citations in this

I'm guessing from the manual title that the answer to all three
questions is no.

Personally, I don't get the point of the "listed under Section ..."
reference either. Why send readers to a list of other manuals in another
section of this manual? You've already told them which other manual to
go to, so that's where they should go, not to your list. Bringing the
list into it is like saying, "See foobar on page 73, as listed in the
index on page 334."


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
rgcombs AT gmailDOTcom


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.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

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

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 for more resources and info.

Would like your opinion...(Reference to Related Documentation): From: SB

Previous by Author: RE: Authoring Tool Called BEAM
Next by Author: RE: laurentiu.stoica,AVCP_Bethel mail system error bounce
Previous by Thread: Re: Would like your opinion...(Reference to Related Documentation)
Next by Thread: RE: Would like your opinion...(Reference to Related Documentation)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads