RE: Warm and Fuzzy Documentation

Subject: RE: Warm and Fuzzy Documentation
From: "Jane Carnall" <jane -dot- carnall -at- digitalbridges -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 29 Jun 2001 14:13:50 +0100

Dick Margulis wrote:
>I think those who are ridiculing Ginny's client for wanting the design to
be warmer and >fuzzier are missing a couple of points.
>First, this is for a client--that is, a paying customer--not a manager.
>Second, we do not know the context in which the client is making the
request. <snip good >examples> There are times when documents _should_ be
warm and fuzzy. Making everything
>look like an engineering brief--just the facts, ma'am--is not always the
best solution.

Dick's right, of course (though a client who expresses this in terms of
"warm and fuzzy fonts" is deserving of a small amount of very quiet and
private ridicule, IMHO, YMMV). Keith Cronin also made some really good
suggestions.

I am currently working on a set of documentation aimed at games developers.
The difficulty here is that my audience is 90% technonerd: they don't read
the documentation, even more than most. (I say this as one who was a
juvenile technonerd, many many years ago...) At the same time, they will
disrespect any attempt to provide a manual in a "for dummies" format: they
*do* know what they know very well, but my documentation is going (I hope)
to bridge that large gap of things they don't know and sometimes don't even
know that they don't know. What I am trying to do is write the documentation
accurately, but with a streak of informality: on-topic jokes, a leaven of
humour. (Talking about it makes it sound silly, but then again I am trying
to talk about it soberly to people like the marketing manager so they won't
think I've just gone off the wall.) My long-term goal: something like Bruce
Togazinni describes in
<http://www.asktog.com/columns/017ManualWriting.html>*

On the other hand, I'm planning to do most of the manual in spiky, cold,
easily-readable fonts. Fuzzy fonts sound like the exact reverse of what
anyone would want to read... <g>

Jane Carnall
Technical Writer, Digital Bridges, Scotland
Unless stated otherwise, these opinions are mine, and mine alone.

*I think this is the correct URL but I was unable to click-check it due to a
lunchtime problem we usually have with the internet.


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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Cub Lea, specialist in low-cost outsourced development
and documentation. Overload and time-sensitive jobs at exceptional
rates. Unique free gifts for all visitors to http://www.cublea.com

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


References:
Re: Warm and Fuzzy Documentation: From: Dick Margulis

Previous by Author: RE: Warm and Fuzzy Documentation
Next by Author: RE: Warm and Fuzzy Documentation
Previous by Thread: Re: Warm and Fuzzy Documentation
Next by Thread: Re: Warm and Fuzzy Documentation


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


Sponsored Ads