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

["Lauren" <lt34 -at- csus -dot- edu>]

Is A suggesting using endnote references in a technical publication?  That
sounds a little absurd.  Maintaining a related documents section could be
alright, but maintaining that section as a static and numbered document can
be a bit much and forcing people to reference that section just so they can
get the name of the document they need to refer to is too much work.  

How many documents does the user need to refer to to perform a simple task?
As a reader, I want to view the manual and, when necessary, the minimum
number of documents that I must read.  A "related documents" reference
section that must be referenced to use the document creates an otherwise
unnecessary step.

Also, what happens when a formerly referenced document becomes obsolete?  If
document number 3 for process X is obsolete because the process is
incorporated into a new process, then what do you do with number 3 and all
of the references that reference that document?  If your document numbering
changes, then all references to all numbered documents will require
changing.

It's one thing to maintain references, but maintaining references to numbers
of references can get way to cumbersome.

I think that A lacks experience in document management.

Lauren
 

> -----Original Message-----
> From: techwr-l-bounces+lt34=csus -dot- edu -at- lists -dot- techwr-l -dot- com 
> [mailto:techwr-l-bounces+lt34=csus -dot- edu -at- lists -dot- techwr-l -dot- com] On 
> Behalf Of SB 
> Sent: Tuesday, August 21, 2007 11:49 AM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Would like your opinion...(Reference to Related 
> Documentation)
> 
> A and I are at odds and I wanted to find out your opinion.
> 
> In a manual, I think that an item (example: name of a manual 
> in the related
> documentation section) should not be numbered if it is a 
> single item and
> there is no "2, 3, etc.".
> 
> A agreed with that but says that one uses the numbering for 
> referencing
> throughout the document.
> 
> For example, when referring to a specific User Manual, he 
> adds a [1] next to
> it (example: New User Manual [1] ).
> 
> [1] means "go see item 1 in Section XYZ under the Related 
> Documentation
> Section".
> 
> Obviously, what he does is shorter but is this clear to the 
> user? See our
> correspondence below.
> 
> 
> 
> 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.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> 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 lt34 -at- csus -dot- edu -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/lt34%40csus.edu
> 
> 
> 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.

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

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.