Re: Advancing the beats
----- Original Message -----
From: "Karsten Wade" <kwade(a)redhat.com>
To: <fedora-docs-list(a)redhat.com>
Sent: Saturday, January 31, 2009 12:32 PM
Subject: Advancing the beats
In my mind, the beats were always potentially more
than just release notes.
I've actually been thinking along similar lines. Perhaps my view is a
little less dramatic, perhaps more so.
I see the release notes as serving two purposes. The first, of course, is
to warn users of changes that might affect them. The second is, in a way,
to "sell" Fedora. For many readers, the release notes are the only bit of
documentation they actually read. To that end, each beat, IMO, needs to
start off with a short sales pitch. Following that, of course, are the gory
details of the changes.
But that doesn't give a user, IMO, a complete picture of all that Fedora has
to offer. The one-liner serves only to pique the reader's interest. It
needs to be linked to content, likely on the wiki, that describes the full
glory of what Fedora has to offer in that particular area.
But wait, there's more. There are many packages that aren't really all that
obvious to get working. The full description of the capability page
probably needs to link to HowTo documents for many of those applications.
This way the user wanting to do something a little less obvious isn't faced
with the black hole of Google. Let's face it, one of the problems with
Linux is that there is so much documentation out there, and most of it was
written for gurus. Finding something that an ordinary mortal can understand
can be maddeningly difficult. A direct chain from the release notes to a
human-readable How-To could be a huge help.
To this end, I have started to do something like that with the Embedded and
Amateur Radio beats. Only just a start so far, and even that is proving to
be more challenging than I expected. I picked these because they appeared
to be nice, little, well-defined areas. But so far, I haven't even got the
total package list for Amateur Radio. Every time I think I'm done I trip
across another hidden cache of packages buried in Fedora's 11K+ packages.
And this area has a SIG that has identified a good portion of the packages.
Paul put together a nice summary for the F10 RN's, and as soon as I get to
the end of a list, I intend to build a more detailed summary for the wiki.
As a prototype for a How To, have put together
https://fedoraproject.org/wiki/User:Jjmcd/Drafts/How_to_use_splat
which describes one of those applications that probably has some widespread
interest (among the amateur radio community) but isn't immediately obvious
how to use. I've asked on the fedora-hams list and also on some outside
lists for comments/suggestions, but so far no input.
The
https://fedoraproject.org/wiki/Applications_for_Amateur_Radio
is at this point not much more than a list, needing to be finished up before
arranging into something a little more readable.
There is something else we need to address, though. Much of the
documentation we have is very uneven, and this applies not only to the RN,
but also the UG and especially the IG. We have some content that is very
step by step and leads the user by the hand. Other content is only
understandable to the true wizard. Somehow we need to sort out how to
segregate, or at least flag that content, so the expert doesn't have to wade
through all that inane babble, while the new user (or potential user) isn't
frightened off by the scary stuff.
Lots to do ... lots to do.
--McD