[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: Advancing the beats




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







[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]