Re: what makes you write community documentation?
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
Attachments:
- signature.asc (application/pgp-signature — 189 bytes)