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

["Jonathan West" <jwest -at- mvps -dot- org>]

On 21/08/07, SB <sylvia -dot- braunstein -at- gmail -dot- com> wrote:
> 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".

It depends on how formal your documentation needs to be, and to an
extent whether different versions of the referenced document exist.

When I was involved with writing European Telecommunication Standards
for ETSI, a distinction was made between Normative references and
Informative references

For Normative references, the clause or standard referred to was by
means of that reference considered part of the referring standard for
the purpose of compliance

Informative references were provided as the name suggests solely for
information.

Normative references were always numbered in the body of the document,
and a numbered list of the References included near the start of
document. In most cases, each item on the list referred to a specific
edition of the referenced standard.

Informative references were also listed, but they were usually undated
references, by which it was understood that you referred to whichever
edition of the document was most recent.

Where the documentation is intended to be published on paper and it is
important that the user is able to identify the full name and edition
of any referenced document, it is a good idea to have a numbered list
of references giving the full title and edition of the referenced
documents (even if there is only one item in the list) and to number
the reference wherever it appears in the document.

If less formality is required, you can get away with not numbering,
not making dated references, or not having a formal list of references
at all. That is for you to determine depending on the nature and
purpose of the documentation you produce.

If the sole means of publication will be electronic, you can arguably
get away with not having a list of references and not bothering to
number the references in the text, but instead hyperlinking alll
references to the referred document.

If you want to see an example of what I mean, you can download ETSI
standards in Word or PDF format from the ETSI website www.etsi.org.
Don't try to download ETS 300 001 (the first in the series) it is very
long!

Regards
Jonathan West
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.