RE: Writing conventions

Subject: RE: Writing conventions
From: edunn -at- transport -dot- bombardier -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 28 Sep 2001 12:05:34 -0400



The only true rule to procedure size and technical documetation that should be
followed with any type of religious zeal is 'Be Consisce'. Say what needs to be
said and no more.

The rule of 7 in IMO is bogus and has been debated on-list many times. It may
apply to short term memory, but cannot be applied to a procedure. To arbitrarily
apply a number is just stupidity, because if you have to set twenty parameters,
you have to set twenty parameters.

If we accept that only one action should be performed per step, and some tasks
cannot be broken into separate subtasks, then there is no question that some
procedures will just have to be ten, twenty, or more steps long. The argument
should never be "there are too many steps", but the procedure should be examined
if it can be broken down. As each industry and indeed each procedure is
different to try and pretend that there is some hard and fast rule is just
rediculous.

I particularily take exception to the idea of lying to enforce an arbitrary
rule. Engineers may indeed not chunk their procedures, but their writing should
be edited with an eye to where the procedures can be broken down and what steps
can be grouped. To say XML needs it that way is setting yourself up to be shot
down. If they find out you made that up only to bully them into doing things
your way, your credibility with them will be reduced to zero and they'll never
listen to any other arguments you may have for them to improve or modify their
way of working.

Eric L. Dunn



>>This company I work for is just now converting
old Word legacy documents into XML and they are finding that most procedures
are very long. The engineers are used to writing long procedures and they
don't really want to change to the "chunking" method. I have been able to
convince them to try it by claiming that XML needs to be "done that way"
(which it does), and they seem to accept it better.

So, basically keeping sentences, tables, and sections short is (or will
be soon) the general rule in most places. If someone out there disagrees,
please let me know.




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

Planning to attend IPCC 01, October 24-27 in Santa Fe? Sign up by
October 3 and get a substantial discount! Program information,
online registration, and more on http://ieeepcs.org/2001/

+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: http://www.axialinfo.com http://www.miramo.com +++

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Follow-Ups:

Previous by Author: RE: Techwriters of the World: Unite!
Next by Author: RE: Writing conventions
Previous by Thread: RE: Writing conventions
Next by Thread: RE: Writing conventions


What this post helpful? Share it with friends and colleagues:


Sponsored Ads