RE: Structuring Documentation

Subject: RE: Structuring Documentation
From: "Damien Braniff" <Damien -dot- Braniff -at- asg -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 14 Dec 2005 09:44:49 -0000

We all use structured writing every time we write something we may not
call it structured writing but thats what it is it's the structure that
makes what we write readable and usable

If we didn't use structured writing then everything would be like my
first para (indeed there'd be only one long stream of text!). Every time
we write a letter or whatever we structure it - we use grammar,
punctuation, spacing etc. Usually we do it without thinking. We've been
taught how to write letters etc. Having said that (just look at letters
written to the papers) there are obviously some people who can write
'better' letters than others be it style, flair, whatever.

Technical writing doesn't come naturally (we're not usually taught it at
school) but we can learn it (like any other type of writing). Also, like
letter writing, some do it better than others :-)

Sometimes we write for ourselves (maybe poetry for our own enjoyment
etc) but, usually, we write to convey information to somebody else - be
it in a letter or a manual. If it wasn't structured then the impact of
that 'message' is greatly reduced and so we 'build/package' the message
in such a way that the reader will, hopefully, find it easy to
use/understand/etc.

How we do this varies from person to person and message to message but
from a TW perspective I'd say:

> Analysis (nobody has said you don't need analysis) - all TW course
talk about task and user analysis. What message is needed and who's
going to read it.

> Once you've got the 'message' and the audience then you can begin to
structure it and here there are a variety of routes to take. One writer
I knew flowcharted the tasks and used that as a basis for the doc. I
tend to do an initial TOC and fill in the heading (adding/removing info
as I go). Some jump right in and start writing.

> Whatever method works for you is fine but, whatever the method, it's
organic and the doc may (often will) change quite dramatically as it
grows. The skill is to use the info gathered in the analysis stage to
create something the user wants! This will involve, wording, graphics
used, layout etc. Knowing your audience means that how you structure the
docs can be tailored to meet their specific needs. Often this involved
knowing what to leave out as much as what to include.

> Different people learn in different ways and the info should meet
their learning style (linguistic, visual, kinaesthetic etc). Usually
this the audience is mixed so you try and provide a mix styles
(text/graphics).

While you do perform analysis you don't always need to know the process
inside out. It's quite possible to write a user manual without knowing
much about how the software works behind the scenes - it may help your
understanding but it may well be totally irrelevant to the user who
wants/needs only step1, step2 etc.


Damien Braniff | Sr. Technical Writer
damienb -at- asg -dot- com

Technical Communications
ASG | asg.com
Waterfront Plaza
8, Lagan Bank Road,
Belfast, N. Ireland BT1 3LR

Tel: +44 (0) 28.9072.3124
Fax: +44 (0) 28.9072.3324

End-to-End Technology Management

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

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.


Previous by Author: RE: Potential Poll Question
Next by Author: RE: Smart answers and useful answers
Previous by Thread: RE: Structuring Documentation
Next by Thread: FrameMaker training


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


Sponsored Ads