Re: LONG - A colloquial writing style?

Subject: Re: LONG - A colloquial writing style?
From: Sean Hower <hokumhome -at- freehomepage -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 11 May 2005 07:47:25 -0700 (PDT)



--------------------------
Steven Brown wrote:
I'm curious to hear if anyone's writing technical
documentation using a less formal, more colloquial
style. (Notice I did not say grammatically incorrect!)
--------------------------
Yep. Used an informal style that used contractions and approached real-world speech without breaking common-sense grammar rules. The tone was also friendly and referred to the user. The documents were targeted at end users with little experience with computers. Part of the style made extensive use of examples that related the product to real-world tasks the users faced. Also included "case studies" that showed characters using the software to do their job.

We got a LOT of positive feedback on this documentation. Many comments about how easy it was to read the documentation and about the quantity and quality of the information. We packed a lot into a very small space.

I find the Dummies books great, but I wouldn't use that style for something like a reference manual. User guide, definitely. But then again, it comes down to audience.

------------------------------
Joe Malin wrote:
On the other hand, you should read the documentation for Mad Magazine's
Collected Issues CDs. The installation instructions, etc are the typical
sarcastic stuff from Mad. It's hilarious!
------------------------------
The instructions for a card game based on the movie "Army of Darkness" are pretty darn funny, but I found them difficult to follow. Same goes for the documentation that was produced at a company I used to work for. In fact, the company was criticized for having funny but useless documentation. Now, I'm NOT saying that you can't have funny documentation that's informative. It all depends on the writer and his or her ability to pull it off. Let's face it, if you're a bad writer, you're not going to be able to pull of any style, formal, informal, coloquial, or otherwise. (Not saying you're a bad writer, just saying that bad writing is bad writing, regardless of the style).



------------------------------
David Neeley wrote:
When the urge strikes to write more verbiage to "make it informal"--
------------------------------
Taking this a bit out of context but I must say that making content informal does not add verbiage. Every time I've rewritten something from formal to informal I've always reduced the verbiage. And in experiments I've done in the past with other writers the informal style almost always yielded shorter, cleaner, clearer content.


------------------------------
Bill Swallow wrote:
We localize into over 20 languages. We literally can't afford to
include colloquialisms in our documentation.
------------------------------
Not saying that you're suggesting this, but does informal=colloquial?




------------------------------
Joe Malin wrote:
You're probably right that Dummies books deliberately choose their style
to be non-threatening. I accept that, though I'm not happy with it. I
don't like "dumbing down", but then again I'm not really the target
audience.
------------------------------
I've read a handful of dummies books, even on topics I knew well and I never felt that these books were dumbing down the content. Just my opinion.






********************************************
Sean Hower - tech writer
http://hokum.freehomepage.com


_____________________________________________________________
Create your own web site for FREE at http://www.freehomepage.com

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

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.



Previous by Author: re: electronic markup of .chm files
Next by Author: RE: Javascript
Previous by Thread: RE: LONG - A colloquial writing style?
Next by Thread: Re: LONG - A colloquial writing style?


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


Sponsored Ads