Self Introduction: Frank

[Karsten Wade]

On Sun, 2007-04-29 at 14:48 -0700, Francis Earl wrote:
> On Sun, 2007-04-29 at 17:05 -0400, Paul W. Frields wrote:

> > The Documentation Project is basically here to oversee such efforts and
> > make sure they maintain high standards of quality.  We're happy to see
> > motivated people stepping up to contribute content!
> 
> I'm not sure how I take this, as I'm not sure exactly how you define
> "high standards of quality". I believe they should be accurate, and I
> believe they should be informative. I'm worried that this also includes
> maintaining a professional feel to the documents. I believe that is the
> wrong approach, depending on the target audience of each document. It
> shouldn't feel like a text book to the user reading it, which is
> somewhat the feel I got from the few documents I have read so far.

I agree that we don't have to have the same tone of voice as e.g. Red
Hat documentation.  That's the text-book feel you are describing.
However, that shouldn't affect quality.  For example, when describing a
set of steps to a user that includes stepping them through a GUI dialog,
it is vital that the wording of the instructions matches what you see on
screen 100%.  Otherwise, the user loses confidence in the document.  I
see such mistakes very often, especially on the Wiki, where it is easy
to whip out a document.

Often a clever voice gets in the way of helping the user, which is why
technical writing often squeezes out the cleverness in favor of clarity
and accuracy.

The same thing is true for grammar.  When a document has common,
obvious, or even subtle wording and grammatical mistakes, it undermines
confidence in the document.  Obviously, I'm a writer, so I have a
prejudice here.

Yet, would we ask our programmers to put out software that had similar
mistakes?  Well, we do, no software is perfect from the start, that's
what the open source process provides us (a chance to continually
correct.)  So, a Wiki can accomplish all of these ends, but *only if*
the team that maintains it can continually move the content toward
clarity, technical accuracy, and grammatical correctness.

It it those requirements that are the basis for this project.  The
Internet is full of how-to-do-stuff instructions that do not meet these
"high quality of standards," and AFAIC, the Internet can keep them.
They do help, sure, while they subtly undermine.  This project is our
chance to correct the undermining and make people's open source
experience that much better. :-)

- Karsten
-- 
   Karsten Wade, 108 Editor       ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20070430/72ce742c/attachment.bin