RE: Structuring Documentation

["Sharon Burton" <sharon -at- anthrobytes -dot- com>]

Tony, your analysis is incorrect. Structured writing exists and I teach it
all the time. For a simple example for something in a user guide: (this
structure is not a "minor formatting issue", it can make or break a document
in that done well, the users can use the doc; done badly or not at all, the
doc is unusable)

Heading 1 or 2
2 or 3 paragraphs here that go in this sort of order:
Topic sentence for each paragraph that explains the point of this paragraph,
built from simple to complex. 2 or 3 sentences after that flesh out the
point or further define the point. These sentences logically flow from one
idea to the next. Not more than 25 words per sentences and not more than 3
to 4 sentences per paragraph, generally. Maybe some bullets or a table to
better organize the text.

Perhaps a conceptual graphic, too, that shows what the words are talking
about to support our visual learners.

Maybe a final paragraph that explains what you need to know/do before you
start. What doing this lets you do when you are done. Notes, cautions,
warnings.
To do what ever
1
2
3

(This is what I've been referring to as information design but it's also
called structured writing sometimes)

I know you love your analysis drawings but the point I continue to hammer
home to you is that you are a visual learner. You are going to love your
pictures. I, like many people, am not a visual learner. I will not like your
pictures. I am a word/hands on learner who gets frustrated with
pictures/charts. Therefore, your manuals will not work for me. There are too
many pictures and charts and that frustrates me and prevents me from
learning what you are trying to communicate. Your manuals will fail for me
and many others. And that doesn't make us wrong, it means that you ignored
your audience and wrote manuals that made you happy.

I think you are looking for some magic bullet that for the writing, for the
construction of words, is like the steps for developing your pretty
pictures. You won't find it. The writing, the construction of words, is the
part that isn't subject to specific procedures/analysis. It's why not
everyone can write and those of us who are good get to make a living doing
it.

There is not a process that tells us how to construct this sentence with
these words and not those words. That is the place where talent, the ability
to write, comes in. Not everyone has it.

sharon

Sharon Burton
CEO, Anthrobytes Consulting
951-369-8590
www.anthrobytes.com
Immediate Past President of IESTC

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


Dick Margulis asks of Tony Markos:


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.
>



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

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.