RE: Structuring Documentation

["Spreadbury, David" <david -dot- spreadbury -at- tellabs -dot- com>]

 Tony,
I have been watching this discussion and have to agree with Dick.

In one sentence below you define structured writing. Analyzing the steps
required to perform some procedure and then putting them down on paper
in the proper order.

Then you say "Structured WRITING (again, outside of minor formatting
considerations) does not exist."

You can't have it both ways. Either structured writing exists or
doesn't.

We prepare numerous procedural documents for the telecommunications
industry. We go into the lab and work through procedures, and in many
cases, work directly with the customer SMEs to ensure that we aren't
missing any steps that the field techs may need (the customer SMEs
'know' how their field techs actually perform the procedures, or at
least how they should be performing the procedures). This is the
analysis, or structured writing, part. Putting it on paper and making it
look pretty, is only window dressing.

Then there are the structured writing tools, such as FrameMaker+SGML. If
this is where your original thoughts were going, that is an entire
different kettle of fish. Using this type of tool can be used to "share
common structure", Dick's comment below.

-----Original Message-----
From: techwr-l-bounces+david -dot- spreadbury=tellabs -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+david -dot- spreadbury=tellabs -dot- com -at- lists -dot- techwr-l -dot- com
] On Behalf Of Tony Markos
Sent: Tuesday, December 13, 2005 8:43 AM
To: Tony Markos; Dick Margulis
Cc: TECHWR-L
Subject: Re: Structuring Documentation

Dick Margulis asks of Tony Markos:

Before you were asking what a structured document was, implying you
doubted that such a thing existed, and now you've just described two
documents as sharing a common structure [an end-user manual and a
properly done software requirements specification].  So do you believe
that it is possible to write a structured document or don't you?

Tony Markos responds:

I had previously asked on this listserv if strutured WRITING existed
(outside of formatting considerations
- a relatively minor thing).  I specifically asked what were the
concrete, specific steps involved in structured writing.  I got none -
only a couple of comments that it is basically a mysterious,
illdefinable black art that "ya just gotta know". 

Addtionally, a fair amount of research on my part revealed nothing more
than loosey-goosey sound bites as to what structured writing is - no
concrete, specific steps.
 
(In all candor, to me, all the above is confusing as I was, prior to
this inquiry, told that the major skill set of a Technical Writer is
skill in structured
writing.)

I did read (pretty sure on InfoMapping web site) that Charles Horn
(structured writing guru) says that structured writing is really all
about analysis.  I also read this on other web sites - which,
additionally stated that actual writing is but a small part of
structured writing.

MY BELIEFS:

*  It is very possible to properly sturcture a document - indeed I do
this all the time.  However, the creation of a structured document is
mainly all about proper analysis. 

*  Structured WRITING (again, outside of minor formatting
considerations) does not exist.
> 
============================================================
The information contained in this message may be privileged
and confidential and protected from disclosure. If the reader
of this message is not the intended recipient, or an employee
or agent responsible for delivering this message to the
intended recipient, you are hereby notified that any reproduction,
dissemination or distribution of this communication is strictly
prohibited. If you have received this communication in error,
please notify us immediately by replying to the message and
deleting it from your computer. Thank you. Tellabs
============================================================
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -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%40infoinfocus.com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.