Numbering Systems for Technical Service Manuals

[eric.dunn at ca.transport.bombardier.com]

Excellent post Dan. Your post was exactly what I wanted (but was too lazy)
to post as soon as I saw the original post about numbering.

Far too often I see "technical" writers complaining about layout, format,
or organisation because they simply "don't like it" or "it doesn't look
right". And then justifying their whole scale design changes on their
limited exposure to one limited field of techwriting and techwriters.

Anyone who will redesign a document or glibly dismiss existing standards
or traditions simply for what "looks better" without researching the issue
and reasons for the style or getting solid evidence the current usage
either hinders production or user understanding without providing benefits
to at least a subset of users doesn't really deserve the title of
"technical" IMO.

While technical documents need not forgo good design, they should not
forgo function for the sake of design.

Reluctantly submitting to the style guide and complaining it's only
"because the engineers want it that way" is little better. As technical
writers, we owe it to our audiences to understand their needs and
requirements as well as the technical information we are trying to convey.

Sometimes too, it requires the humility to understand that the
system/layout you don't like may have no logical or relevant reason behind
it, but not liking it is just as baseless a decision. In the event of
conflicting arbitrary decisions, continuing with the current standard for
consistency is usually the way to go. So, if you want to make a change,
you need not prove the previous method wrong, but prove the new method
superior.

Daniel Emory wrote on 05/17/2006 10:36:11 PM:
> Even relatively simple on-line help docs should have
> some sort of numbering scheme. Typically, users who
> can't figure out something from the on-line help will
> resort to a customer help line or in-house expert. If
> the user can give the help specialist the number of
> the particular on-line help content where the user is
> stuck, ambiguity is eliminated, a successful
> resolution of the problem is more likely, and the time
> to arrive at the correct solution is likely to be
> minimized.

Too true. If the numbers wouldn't describe structure, even a random number
(the internal help topic number?) that could be made visible would make
referencing, commenting, and updating the system much simpler.

Or, in my experience, the user may be able to stop travelling a circular
path of references a little sooner if the organisational structure of the
help file was more apparent. Perhaps the numbering may even avoid
confusion between two similar yet subtly different topics.

Eric L. Dunn
Senior Technical Writer

_______________________________________________________________________________________________________________


This e-mail communication (and any attachment/s) may contain confidential
or privileged information and is intended only for the individual(s) or
entity named above and to others who have been specifically authorized to
receive it. If you are not the intended recipient, please do not read,
copy, use or disclose the contents of this communication to others. Please
notify the sender that you have received this e-mail in error by reply
e-mail, and delete the e-mail subsequently. Please note that in order to
protect the security of our information systems an AntiSPAM solution is in
use and will browse through incoming emails.
Thank you.
_________________________________________________________________________________________________________________



Ce message (ainsi que le(s) fichier/s), transmis par courriel, peut
contenir des renseignements confidentiels ou protégés et est destiné à
l?usage exclusif du destinataire ci-dessus. Toute autre personne est par
les présentes avisée qu?il est strictement interdit de le diffuser, le
distribuer ou le reproduire. Si vous l?avez reçu par inadvertance,
veuillez nous en aviser et détruire ce message. Veuillez prendre note
qu'une solution antipollupostage (AntiSPAM) est utilisée afin d'assurer la
sécurité de nos systems d'information et qu'elle furètera les courriels
entrant.
Merci.
_________________________________________________________________________________________________________________




(See attached file: C.htm)
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: C.htm
URL: <http://lists.frameusers.com/pipermail/framers-frameusers.com/attachments/20060518/c40fe88f/attachment.txt>