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

[Ned Bedinger]

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