empowering the user and traditional tech writing - style discussion

[Karsten Wade]

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.

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].

For example:

"You can click on Applications > Sound & Video > CD Player to start the
audio CD application."

v.

"Click on Applications > Sound & Video > CD Player to start the audio CD
application."

And so forth.

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

- Karsten

[1] Markestpeak == language used in marketing products/services, which
is deliberately personal

[2] Cheerleader-writing == my term for writing with lots of exclamation
points!  You'll love it!  Or not!  But you just can't make it stop!
Yes, I used to edit my high school newspaper.

-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

[Dimitris Glezos]

O/H Karsten Wade έγραψε:
>  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.
>  
>  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].
>  
>  For example:
>  
>  "You can click on Applications > Sound & Video > CD Player to start the
>  audio CD application."
>  
>  v.
>  
>  "Click on Applications > Sound & Video > CD Player to start the audio CD
>  application."
>  
>  And so forth.
>  
>  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
>  
>  - Karsten
>  
>  [1] Markestpeak == language used in marketing products/services, which
>  is deliberately personal
>  
>  [2] Cheerleader-writing == my term for writing with lots of exclamation
>  points!  You'll love it!  Or not!  But you just can't make it stop!
>  Yes, I used to edit my high school newspaper. 
The use of 'you' is even more tricky in some languages (like greek), where the
plural 'you' is different and the adjectives/etc change too. For example,
translating "Are you sure you want to insert this?" becomes something like:

  "Είσαι σίγουρος πως θέλεις να το εισάγεις αυτό;"
  =
  "Are you (singular number exposed) sure (masculine gender exposed) you want
(singular) to insert (singular) this?"

So, we try to hide it, by using plural form and indirect speech:

  "Σίγουρα να γίνει η εισαγωγή αυτού του αντικειμένου;"
  =
  "Surely should this to be inserted?"

Of course, this leads to *even more* formal/distant/indirect writing than just
avoiding the presence of the word 'you' and even less user-motivation as Karsten
mentioned.

So, what's my opinion on this? Not sure. Probably something in the middle. The
text does seem of better quality and is more accessible. On the other hand, if
people don't read it (or it doesn't have an effect), it's useless.

One could see two groups of texts here:

  1. The guides/tutorials
  2. formal, must-be-objective texts, like press releases, encyclopedia
articles, short-texts like application buttons).

The goals of the guides are to not bore the user (have him read the whole text)
and urge him to do something. It's more like giving him a hand than stating
things, which is more like the second group. Having a slightly less formal
wording in these cases might accomplish their goals in a better way than the
formal wording.

-dim


PS: Please excuse my poor english. If I wasn't clear, I agree with Karsten. ;-)


-- 
Dimitris Glezos
Jabber ID: glezos(a)jabber.org, GPG: 0xA5A04C3B
http://dimitris.glezos.com/


"He who gives up functionality for ease of use
loses both and deserves neither." (Anonymous)
--

[Gain Paolo Mureddu]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Dimitris Glezos escribió:
>  The use of 'you' is even more tricky in some languages (like greek), 
where
the
>  plural 'you' is different and the adjectives/etc change too.
> For example,
>  translating "Are you sure you want to insert this?" becomes something like:
>
>    "Είσαι σίγουρος πως θέλεις να το εισάγεις αυτό;"
>    =
>    "Are you (singular number exposed) sure (masculine gender exposed) 
you want
>  (singular) to insert (singular) this?"
>
>  So, we try to hide it, by using plural form and indirect speech:
>
>    "Σίγουρα να γίνει η εισαγωγή αυτού του αντικειμένου;"
>    =
>    "Surely should this to be inserted?"
>
>  Of course, this leads to *even more* formal/distant/indirect writing 
than just
>  avoiding the presence of the word 'you' and even less
> user-motivation 
as Karsten
>  mentioned. 
It happens something similar in spanish, but thankfully we have a
"neutral second person of the singular" pronoun: "Usted", which can
even be obviated by the way the verbs are conjugated. Sticking to the
example you provided:

"Are you sure you want to insert this?" Would translate to something
similar to:

"Está seguro de insertar esto?" Or "¿Está seguro de querer insertar
esto?"

I too, at first was confused with the lack of gender distinguishing in
the English language other than by pronoun (i.e there is no way you
can determine if a conjugation is masculine or feminine just by the
conjugated formula, also applies to adjectives where you require the
pronoun), like "seguro", masculine, often neutral form of "sure",
also
refers to a masculine subject and "segura" feminine, refers only to a
feminine subject (so no gender confusion here).

I think that the objective for a "neutral" writing style can be
achieved in any language, problem is that what will be required is
often a good understanding of the original language a piece is written
in, to be able to translate. You know that old Italian saying?
"Traduttore, traditore" which means "Translator, traitor", because
you
can't possibly translate vis-a-vis from one language to another, there
are simply linguistic forms and formulas that untranslatable across
languages, that's when as translator you have to keep to the context
and try to express the original punctual linguistic form into a more
descriptive one, and vice versa, some languages need too many words to
express something where others only require one or two, etc.
>  So, what's my opinion on this? Not sure. Probably something in the 
middle. The
>  text does seem of better quality and is more accessible. On the other
hand, if
>  people don't read it (or it doesn't have an effect), it's
> useless.
>
>  One could see two groups of texts here:
>
>    1. The guides/tutorials
>    2. formal, must-be-objective texts, like press releases, encyclopedia
>  articles, short-texts like application buttons).
>
>  The goals of the guides are to not bore the user (have him read the 
whole text)
>  and urge him to do something. It's more like giving him a hand
> than stating
>  things, which is more like the second group. Having a slightly less formal
>  wording in these cases might accomplish their goals in a better way 
than the
>  formal wording.
>
>  -dim
>
>
>  PS: Please excuse my poor english. If I wasn't clear, I agree with 
Karsten.
;-)
>  
Well, I thought that this is why there are "Editors", who will read
and provide feedback to the original author(s) and make sure the
language and wording are accurate and clear. Not only from a technical
perspective, as the Editor does not have to "know as much Linux or
about Fedora as the original author", but the job of him is to help
the original author to correctly express that which (s)he wants to
say, so it could be understood by non technical readers or a broader
audience.
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.5 (GNU/Linux)
> Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org
>
> iD8DBQFE+IHrXM+XOp70dwoRAiV4AJ0QZZyPoIWKTIy55X90+rlELEpjuACfQRvE
> JJ4cMO4mwVVncgZDVzFFjcs=
> =ao3H
> -----END PGP SIGNATURE-----

[Paul W. Frields]

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_marketi...

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

[Patrick W. Barnes]

On Friday 01 September 2006 11:35, Karsten Wade <kwade(a)redhat.com&gt; 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.
>
>  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].
>  
...
>  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
>  
First, I'd like to point out that I haven't forgotten about the Style Guide, 
and I fully intend to consider this thread when I resume work on it.

I come from the camp of "never use 'you' unless engaging the reader 
directly" -- an approach that has served me well.  As I work on the Style 
Guide, I intend to make it an example of the best case scenario for technical 
writing and avoid "you" altogether, but some documents, particularly how-tos 
and FAQs, will take a slightly different style, where "you" might sometimes 
be appropriate.  Marketing materials, such as banners and flyers, are a whole 
different ballgame.  Their styles are very different from the technical 
documents but are something we will sometimes tackle.  I will try to cover 
some of the style variations in the Style Guide as it progresses.

-- 
Patrick "The N-Man" Barnes
nman64(a)n-man.com

http://www.n-man.com/

LinkedIn:
http://www.linkedin.com/in/nman64

Have I been helpful?  Rate my assistance!
http://rate.affero.net/nman64/
--