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

[Ned Bedinger <doc -at- edwordsmith -dot- com>]

SB wrote:
> A and I are at odds and I wanted to find out your opinion.
> 

<snip>


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

If you are writing manuals for switches, I'd guess your company has an 
established style for such things, so you should probably defer to the 
house style and avoid doing it the way you or [A] want.

If you have no established house style, then the safe way to do these 
cross references is to look at how they are done in the manuals used by 
the audience and aim for consistency. IOW, you and [A] ought to see what 
the users want or expect in this regard.

BTW, my experience with people who need a switch manual is that academic 
style would not be a good choice, because they usually have gotten their 
training from the military or technical school. Academic style would not 
necessarily be familiar to them. There are some university-trained BSEE 
and MSEE people working in telecom infrastructure, but they're the 
exception.

HTH.

Ned Bedinger
doc -at- edwordsmith -dot- com




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

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.