Re: how to recruit writers

[Karsten Wade]

On Thu, 2005-03-31 at 18:51 +0200, Duncan Lithgow wrote:
>  Hi, this sounds like something for me to pipe up on. I've
> recently
>  joined this list because I'm very keen to see improvements in docs for
>  linux generally. Here are some of my thoughts.
>  
>  - it's wrong to think that newbies can't write docs, they can best write
>  docs for other newbies about things they've just come to grips with.
>  this means that docs need to be (at least) as easy to edit as wikipedia.
>  Another good example that springs to mind is the php manual.
>  http://www.php.net/manual/en/configuration.php 
Yes, definitely the newbie factor was an oversight in my original post.
There was a follow-up a few hours later in support of what you are
saying.

>  - the absence of docs written for non-nerd windows users on how to
> get
>  started in linux is horrendous. All the things I've seen either
>  oversimplify or are written for command line types. 
I agree that Fedora docs needs to stretch from the newest to the oldest
user.

>  - the fact that so many distros have their own completely seperate
> docs
>  for the *very same programs* is absurd. ubuntu springs to mind - great
>  project, but a lot of reinventing the wheel as far as much of their docs
>  go. 
This is not likely to go away.  Go to a bookstore and into the computer
book section, you won't find one book for each topic.  Go to your
favorite distro and see how many mail clients there are.

Still, there is value in adopting upstream documentation.  We could
consider that for some areas such as GNOME.  I want to review it on a
case-by-case basis.

>  In the course of writing this it strikes me that there are three
> main
>  levels of doc-writers. It *must not* be a locked and/or techhead
>  oriented issue.
>  
>  * Top level: Full editorial power - responsible for maintaining a
>  logical structure for the docs.
>  * Middle level: 'Node editors' - edit any given page of the docs, but
>  not the logical structure.
>  * Bottom level: Joe public - able to add comments to a page. Comments
>  may or may not be included in 'official doc releases' but always give
>  ideas for those editing the docs. 
This idea works for a Wiki pretty well.

I think there is a natural limit to how useful purely collaborative
documentation is.  When it comes to an action that can destroy or make
surprise data changes, I'd like Fedora users to know they can come to a
more trusted authority.  For example, I've used forum answers at
linuxquestions.org as a starting place that helps refine the search.
Rarely is the final answer to be found there.

Much of the easy and useful pieces have already been produced by the
Fedora documentation efforts.  Those have a different scope than we do.
Full tutorials and how-to documentation is different from short how-to
documents.  We take more time to write longer documents, but the result
is something that is well tested and useful to a wide audience.  It is
something worth maintaining, instead of a collaborative posting that may
get abandoned.

One of the founding principles of the Fedora docs project was to attempt
the quality of Red Hat Linux documentation.  To do this requires a more
formalized writing discipline.  It's like the difference between an
article published in a magazine and a blog.

All that said, I agree that we can consider some of our content areas
and audience as being best served with collaborative docs in a Wiki.
I'd consider these on case-by-case basis.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/