[documentation] What's wrong with "you"?

[Steven Peck]

The style guide is an artifact of the original team several years ago.
 If an alternative style is desired and proposed and seems an
improvement (i.e. takes valuable lessons from existing stuff) then
there is nothing preventing the discussion.

If I like it and it gets good feedback, then I am willing to change.

Keep in mind that even with the style guide we have several different
audiences of users.

On 10/31/07, Lynette <esmerel at logrus.com> wrote:
>
> I completely agree - I review several thousand pages of software
> documentation every year. I also write a lot of short bits of things
> that are directly user/customer facing, with the purpose of explaining a
> problem, a function, or a specific task they need to accomplish.
>
> Our docs only use the 'you' form, because we the writers, are telling
> you, the readers/users, what to do. First, you do this. Next, you do that.
>
> It's been a great improvement for us. Our users feel it is much much
> clearer and easier to understand what they have to do. If it doesn't say
> 'you', it is most definitely implied. I will note though, our
> documentation is extremely task based. That may not always be the case
> in Drupal's documentation.
>
> Besides, the greatest thing about standards... there's so many to choose
> from.
>
> - Lynette
>
>
> <bits below hacked for brevity>
>
> O Govinda wrote:
> >
> > Chris Miller-18 wrote:
> >> http://www.ent.ohiou.edu/~valy/techwrite.html
> >>
> >> The convention for technical writing is third person.  In a diverse open
> >> source community like this, use of "you" allows too much loose,
> >> spoken-type language slip into technical writing.  In the IBM license
> >> example, there has to be some label to identify the parties in the
> >> contract, so I don't consider it a good comparison.
>
> >
> > Which style fits better for documenting Drupal?
> >
> > If this example and the one from IBM aren't close enough, here's another,
> > chosen at random from the help texts written--by professionals expert in
> > documentation--for Windows Vista:
> >
> > And so on. "You. . . you . . . you. . ."
> >
> > So while, yes, third person may be the standard for technical writing, to
> > tell someone how to do something (like use Windows or Drupal) nothing quite
> > beats "you."
> >
> > Cordially,
> > O Govinda
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>