what makes you write community documentation?

[Paul W. Frields]

On Mon, 2007-08-06 at 07:51 -0500, Dan Smith wrote:
[...snip...]
> The problems I see with the project start with the complexity to
> actually write something. First nobody knows what needs written. 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. 

We are always on IRC and here, and it's our policy and practice to give
people help with account creation whenever they ask.

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

Unfortunately, this strategy goes against most fundamental tenets of
both adult education and technical documentation.  The right way to do
things is not to show a slew of solutions and let the user pick.  The
user has already consulted documentation because they don't know how to
pick; it's the job of the core documentation to give the simplest and
most efficient solution.  This doesn't mean there can't be auxiliary
documentation about many solutions; there are many examples of good docs
that do just that.  But before doing any documentation in that realm, we
need a stronger core docs set.

> Another impediment is the access control. I never could edit wiki
> content. Maybe my ID finally got straitened out, maybe it didn't. I
> heard other users complain of same thing on this list. So the two docs
> I did write never got submitted. I pasted one in frustration into the
> list. Got good constructive criticism on many parts on others I felt
> the scope limitations were going to limit my ability to write
> meaningful documentation. The other which was probably more in line
> with the kind of docs being asked for I never could submit. I tried
> for weeks. Exchanged emails trying to find the right person to ask
> about getting my rights corrected. Finally just gave up. 

If you would like to try again, we can lead you to the pages with simple
step-by-step instructions for getting this set up.  If they don't work,
we would like to hear exactly (and concisely, please) what failed, so we
can (1) help you, and (2) fix the docs.

> Second do we really want people editing content directly? Shouldn't
> that go through a review before being placed out there?  So why not
> have a submission process? Submit it for peer review, corrections,
> additions. This means no more fumbling in the dark trying to figure
> out how to add content or getting frustrated when your account isn't
> given sufficient rights. People tend to feel slighted when that
> happens. I'm sure no slight is intended. I've seen no malice on this
> list toward people. No cliqueism or people feeling above others. Folks
> seem quite friendly and very interested in doing a good job. 
[...snip...]

The whole point of a wiki is to bypass the bureaucracy and stifling
nature of time-delayed review.  Wiki changes are in fact reviewed by
anyone who wants to put a watch on a page or set of pages using the
wiki's built in functionality.  I am not a big fan of the wiki for
official documentation of any kind, but for collaborative drafting it is
at least passable.  In fact, our release notes are created in just that
fashion.

Karsten has put significant time into lowering any remaining access
barriers on the wiki.  As soon as the new wiki software is released by
its developers and installed on fedoraproject.org, things will get quite
a bit easier there.  I would encourage you to push through with getting
your access fixed, and then contribute to the core documentation set so
we have a place from which to jump off into other short tutorials as
needed.

I would also encourage you when you correspond on this list to (1) use
plain text when you post, to respect those readers who require it; and
(2) exercise some brevity, which makes it more likely you'll get
thoughtful responses.  Very long emails, for which you seem to have a
proclivity, tend to discourage responders who are trying to fit their
list-reading time in around a very busy schedule.  Thanks for responding
and let us know how we can help you with access.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
      Fedora Project:  http://fedoraproject.org/wiki/PaulWFrields
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
-------------- 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/20070806/dc0333de/attachment.bin