empowering the user and traditional tech writing - style discussion

Paul W. Frields stickster at gmail.com
Fri Sep 1 18:03:04 UTC 2006


On Fri, 2006-09-01 at 09:35 -0700, Karsten Wade wrote:
> We need to discuss our writing style approach; I think it's too late for
> FC6, so we need to stick with what works for now.  But Paul W. Frields
> challenged me with the idea of empowering the user and having a specific
> style to support that.

I hope it wasn't an *unwanted* challenge, we have so much to do already!

> In traditional tech writing, we try not to use pronouns yet keep an
> active voice.  It makes for a cleaner writing, easier to translate, and
> has fewer assumptions implied about the reader, which helps to make it
> more accessible.  It also sounds less like marketspeak[1] and
> cheerleader-writing[2].

Interestingly, this comes at least warm on the heels of this
semi-related post:

http://headrush.typepad.com/creating_passionate_users/2006/08/why_marketing_s.html

Maybe that's just a *tad* overboard.  As Karsten and others who've been
around this list a while know, I'm a big fan of the Red Hat official
docs.  They're well-written, well-organized, and full of juicy content.
Plus, they are diligently cross-referenced.  They're also fairly devoid
of pronoun usage IIRC, and a great primer for anyone getting started in
tech writing:  If you digest their style, you'll know, for the most
part, how to do tech writing that doesn't make your editor want to
strangle you with both hands.

What I talked to Karsten about was the idea that tone might in fact
depend on the audience for a specific work.  Many readers, especially
rank beginners, might conceivably be put off by the crisp, no-nonsense
approach we favor.  I'm definitely *not* in favor of turning everything
we write into the fourth-grade English one finds in so many one-off Web
tutorials.  But the DUG -- the context in which this issue arose --
might be just a tad different than our average Guide.

This was one of the main reasons I inserted an "Assumptions" section in
the introduction.  It also goes back to why I was a proponent of the
tutorial/guide introduction section, and in particular a similar
subsection that addresses the knowledge, skills and abilities the reader
must have to successfully understand and put to use the concepts and
practices in the tutorial.

> However, a blanket rule to "never use 'you'" might be wrong.  At the
> least, we can discuss here what we want to do.  Perhaps we can break
> some new ground, or at least join the 21st century. ;-D

The rule I've been quietly operating under has been to avoid "you" when
possible, but to use "you" when eliminating it would either hurt the
meaning of the text, or would break other more important rules.  I
despise passive voice, so a change Karsten made in the DUG which created
passive voice really made me think about this usage.  That got me
thinking about why the DUG should be a certain way, or not, and made me
remember the blog post linked above.

That entire blog is very interesting, I think, because it captures the
idea that *using technology should be fun*.  In fact, the central tenet
seems to be "Help the user kick ass."  That's a good motto, I think, for
something like the DUG.  Perhaps it's not so good for more technical
guides, which may serve as a primer for people using Linux for very
serious purposes, like running a Web server for a business, or
safeguarding customer data.  Certainly the target audience for the DUG,
though, demands a gentler approach.

In any case, I hope people will consider the idea, and really look at
the assumptions about the people reading, and how the text is addressing
them.  Thanks for putting up with my ranting comments in the DUG, hope
they didn't get on anyone's nerves. :-)

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
       Fedora Project Board: http://fedoraproject.org/wiki/Board
    Fedora Docs Project:  http://fedoraproject.org/wiki/DocsProject
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060901/4dfc1831/attachment.sig>


More information about the fedora-docs-list mailing list