SUMMARY: Writing for HTML

[Tammy Hale <tammyh -at- FGM -dot- COM>]

Hey everyone,

Thank you for your input on the writing process of online documentation.
The responses to my question have now dwindled out.  I thought this would
be a good time to summarize the responses for the list.

I got the impression that people weren't really interested in discussing
the writing process as much as they were interested in discussing
organization. I think the reason it's difficult to stay focused on the
process is that the organization of a doc is crucial; how you get there is
not so crucial.

Most people responded via private e-mail, and almost as many asked that
responses be forwarded to them or posted to the list.  Because people
responded privately, I'm assuming they don't want me to use their names.

***Summary of How to Organize an HTML document:

We all seemed to agree that you should chunk info, place links where
relationships exist, and limit the number of links so the reader doesn't
get lost.

***Summary on the Writing Process

1. One person stated that you *can't* outline a hypertext document: "What I
do instead of outlining is draw large areas and put my chunks in there.
Then I draw lines where a relationship exists. My approach is similar to
that described in a recent (not the most recent, but the one just before
that...) issue of _Communications__of_the_ACM_.  It is rather similar to
modeling databases..."

2. Another person wrote that preparation for writing for on-line is the
same as writing for paper, only the organization of the document is
different.

3. Someone else agreed:  "Basically, I think the process is the same. I did
my page kind of haphazardly, but I did have a general scheme in mind and I
think in that respect writing for a web page is no different from writing
an actual document.

3. Another angle:  "I find myself trying to 'picture' the document
more--take a guess at how the different viewers will show it.  As a result,
I try to get as much
information as possible into as few words.  I find myself organizing
things in smaller chunks.  Some of the questions I ask myself are:  what
do I want the first screen to show?  How do I organize the material so
that someone can walk through the process?  How do I make sure the
process flow works?"

On the topic of outlines, the same person wrote "I do think [an outline for
an on-line doc] is more similar to a flow chart than an actual outline in
that you're dealing with an end user who can 'access' the process at many
different levels where an outline tends to be more of a 'start at the
beginning and work your way to the end' deal.

"...I find myself not nearly as concerned over layout (fonts, paragraphs,
etc.)."

4.  Another person responded about outlines: "I have found that a flowchart
does not work for large online documentation projects. There can be so many
links that eventually the chart turns into a jumbled mess. I generally do
an outline for an online project in the same way as I do for a paper
project. Generally, each headiing is its own individual topic (file). I
also list all the links for each topic in a database so I can keep track of
which are completed."

5.  And the final comment on outlines: "In what I've seen in my experience,
outlines for online documentation of any kind are flow charts because you
are linking your information to other references as opposed to pointing as
in a printed document.

"The process I would suggest is:
1.  Product a flow chart outline of the html document you want to product.

2.  Put it aside.

3.  Review it after a few days.

4.  Revise based on your review.

5.  Give it to a peer or supervisor (with html experience preferred) for review.

6.  Revise it based on their review(s).

7.  Have a storyboard session with your client or development and QC
departments depending on the size of your employer/contractee.

8.  Revise based on the storyboard session.

"As you can see, it's not much different from the normal printed material
writing process."

***End of summary.



Thanks again!

Tammy
tammyh -at- fgm -dot- com