Docs Project: how well are we doing?

[Jonathan Roberts]

Hey,

Sorry if this is long or not what was wanted, but hey, if it is just
skip over it!

> Fedora 8 is approaching, as it happened in the past, there are very few people
> actively working on our Docs -- so few we are thinking of just focusing on
> delivering the release notes and install-guide for this release. The Desktop
> user guide hasn't even been updated for F7.

I did some work on updating this guide in the build up to Fedora 7's
release, but I didn't go further because I felt like the goals of the
doc/direction it was going in weren't clear and I didn't know what
still needed doing. I asked a couple of times, and thanks to jmbuser
for providing some pointers Re: this, but I still felt lost in the
end, like the guide was aimless. Maybe I should have pushed further,
but some other things came up at the same time and my attention was
switched.

> While it seems that we've got very few contributors, on the other hand, we see a
> bunch of people joining the project, posting self introductions that show
> willingness to help! Which is great!
>
> An obvious Question comes in mind then: what are we doing wrong and all you new
> contributors aren't involved in a Doc having fun and everything? What didn't you
> like when you first joined the project? What did you expect and where did you
> get disappointed?

Hmm, it's difficult to be specific with this question, but I'll do my best.

I came along with a huge amount of enthusiasm (mostly as a result of
wanting to give something back for all the software I've had for free,
wanting to help others out, the usual reasons) and time. I think
initially I did some useful work? I hope so!

As time wore on though, I found myself with a bit less time than I had
before, and felt a little bit confused about where to contribute. Some
of the ideas that were tried, with respect to direction, had real
promise I think - the timetable, focusing on one guide at a time etc -
but none of them really picked up momentum (see my earlier point about
the DUG).

Another thing that put me off was the very formal style selected by
the project. I appreciate that there are good reasons behind this -
consistency, clarity, authoritative tone etc - but it's a bit of a
chore to write like that: it doesn't feel natural (maybe just me?),
and it's dull to read back. One thing that I think the project should
consider, as the wider Fedora project has been discussing lately, is
"what is our target audience?": while the formal style is great for
docs from Red Hat/Microsoft etc (wow never thought I'd write that!)
which are aimed at cooperate users, is it right for
$fedora_target_audience - is it suitable for, what is currently a
small team, to maintain?

Perhaps alternative styles of docs could be tried? I've recently been
playing with openSUSE a bit (as a result of the target audience
discussions) and found that they've got a project to create community
contributed "cook books". A Fedora implementation could perhaps see
community contributed recipes, through whatever medium (e-mail even!?
legal aside), while the small core team could edit and pull things
together (polish), and obviously write recipes themselves!?

Other things I think are important I've talked about in the past:
clear to-do lists of what needs doing so contributors know what to do
etc.

I hope this is useful to people? I'd love to start contributing again
in the future but starting uni next month may take up some of my time,
at least while I get settled; maybe in a few months I can become more
active again, and hopefully I won't feel so lost then as well :D Also,
my apologies about the Revisor guides - I still hope to be of some use
with these in the future!

Jon

p.s. You guys do great work as it is: rel notes/inst guide/tools etc are superb!