Re: LONG - A colloquial writing style?

[David Neeley <dbneeley -at- gmail -dot- com>]

It seems to me that there are several different aspects to "writing informally."

One is tone. Addressing the user directly, using more natural-seeming
contractions, keeping the language relatively simple--all these can be
extremely valuable in a doc, I find.

On the other hand, there is a fine line between "using narratives with
names" and being "cutesy." The first is merely an informal method of
doing use cases, after all, while the latter comes across as talking
down to the audience--and that is usually the kiss of death to having
attention paid to the documentation.

One challenge is keeping the material brief; another is to make needed
information extremely accessible.

In my view, it is a major mistake to assume that readers will read the
doc sequentially from start to finish. Overwhelmingly, the tendency is
to skim through all but that which is being sought to solve an
immediate question or concern.

When the urge strikes to write more verbiage to "make it informal"--I
suggest you resist that urge unless and until you can also make it
easy for the typical user to find what they need quickly and
efficiently.

David

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

New from Quadralay Corporation: WebWorks ePublisher Pro!
Completely XML-based online publishing. Easily create 14 online formats, including 6 Help systems, in a streamlined project-based workflow. Word version ships in June, FrameMaker version ships in July. Sign up for a live, online demo! http://www.webworks.com/techwr-l

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