what makes you write community documentation?

[Karsten Wade]

On Mon, 2007-08-06 at 07:51 -0500, Dan Smith wrote:
>  Most distro documentation is about like man pages.  It tells you that
> yeah you can use a digital camera. Just wait for it to pop up. That's
> not real useful in troubleshooting if it doesn't. That doesn't help
> somebody who wants to get accidentally deleted photos off the camera.
> It states the obvious without giving any real help. Folks turn to
> documentation mostly for help. 

I wanted to highlight this observation.  It is true, and as you
surmised, the reason (for example) camera usage isn't covered in more
detail is simply a shortage of writers.

Anyone can get an account and edit this page:

http://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide/Photos

Account creation really isn't that hard, and helpful people are
everywhere.

> The problems I see with the project start with the complexity to
> actually write something. First nobody knows what needs written. 

http://fedoraproject.org/wiki/DocsProject/Tasks

> I suggest a greeter committee spend some time in IM and or email
> exchanges and get to know new volenteers. Walk them through the
> process of account creation. How things work. Get a feel for their
> skills and connect them with areas that need work. 

Extensive examples of this exist in the email archives and IRC logs.
Project members have always made themselves accessible to contributors,
new and old. Personally, I can't do much more.  

We need concrete suggestions that we haven't already tried.  We'll
continue to beat that old drum as you suggest, but we either need a new
rhythm, a new drum, or a new drummer.

> Second I suggest more flexibility in the docs. Lets show people the
> strength of Linux, not restate the obvious. I gave some examples and I
> hope I didn't offend anybody. I suspect that they may have had more
> detailed documents but that decisions were made to make it ultra
> simple. The problem is ultra simple got to be so simple it's useless
> in my opinion. Lets take playing music for example. 

We have made a conscious decision to provide information to users who
may not be familiar with what is obvious to you and I.  Content always
needs improvement.  Just remember that most of the content out there is
exactly like you describe -- it figures a relative familiarity with the
technology, focuses on various ways to solve problems, and covers a
diverse set of tools.  Why should we do it just like that?  This isn't
the "Linux Docs Project", it's the "Fedora Docs Project".

In a default working environment install of Fedora, there are a series
of menus.  It is those applications that are good examples of what to
cover.  Beyond that is less useful, because it includes applications new
users are not likely to see.

> Topics I personally think should be covered are. 
[snip good topics]

Anyone is welcome to cover those topics, within legal-in-the-US
guidelines.  But as the Docs Project, we have to focus on one or a few
things to be successful at it, and why not "Users new to the Fedora
desktop working environment"?  

For example, there have been numerous requests for KDE content, but no
one has stepped up to write it.  When someone does, we'll have it.  But
it isn't reasonable to ask for a change in the commitment of resources
for what you think is a good idea.

> In my opinion the red tape surrounding docs 

I'm sorry you had a bad experience.  It happens.  We all try to help
each person with whatever they need.  There are many success stories,
and an unknown number of failures.  People fall through the cracks, no
matter how hard we try.  There is a reason that any barriers are in
place, and we're always working on making them easier to hurdle.  But
persistence always works out in the end.

> Second do we really want people editing content directly?  Shouldn't
> that go through a review before being placed out there?  
[snip]

Few thoughts here:

* You are suggesting adding a lot of work for a small group of current
contributor volunteers.

* Your model is a little out-of-line of the open source/open
collaborative model

* Does it really lower the barriers or just put all the barrier work on
people instead of tools and processes?

Wherever possible we need to make people able to control their own
destiny in Fedora.  We need to hold their hand as much as they need, but
not forever.

> So it's more a matter of organization really. There are lots of people
> who want to help. They don't know where to help, how to help. They
> come in and feel like outsiders. The red tape is confusing. There is
> no process to make sure they know what is expected of them. The work
> to do work can be exasperating and confusing. Create a sig, create
> accounts here, there and hope that all the various people in each step
> get it right and that the new members do it correctly. 

Fedora has a responsibility to the longevity of the project.  Since all
of this used to be a closed loop inside of Red Hat, opening up those
resources requires care.  There has been a reasonable position between
"no barriers" and "too many barriers".  For example, if we ever have to
change our content licensing again, as we had to from GFDL to OPL a few
years ago, we are *all* going to be happy that contributors and content
are covered under the individual contributor license agreement (CLA).
The CLA looks like a hassle, until you need it.

> What I suggest is that this process is streamlined. The welcoming
> committee can filter out the passing ships and filter based on
> ability. They can walk folks through the initial process of getting
> all those accounts created. They will actually know who to buzz if the
> rights are set wrong. They can also help get people to areas where
> they will do the most good. There are two types of people needed in
> projects like this. The organizers who unfortunately will probably
> spend more time working with people than on actual docs and the
> writers. The fewer organizers the more get's written. The more the
> ogranizers do the more time writers have to write. 

That sounds like what happens on this list.  Isn't that the case?
People are welcomed, directed or led or left alone, as per their
preference.  I understand that may not have been your experience, I'm
sorry, but you use the third-person (they, them) as if you've done a
wide ranging poll of people frustrated with Fedora Docs.

- Karsten
-- 
        Karsten Wade              ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
    quaid.fedorapeople.org        |          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/20070807/c2464a9f/attachment.bin