Advancing the beats

[John J. McDonough]

----- Original Message ----- 
From: "Karsten Wade" <kwade at redhat.com>
To: <fedora-docs-list at 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