It was cool to see the naming scheme Sparks chose for the beats:
https://fedoraproject.org/wiki/Documentation_Beats https://fedoraproject.org/wiki/Documentation_Boot_Beats
In my mind, the beats were always potentially more than just release notes. The Fedora Weekly News actually uses the beats concept more successfully -- the natural flow from writer to the audience in a single publication makes sense.
By contrast, the release notes have always suffered from content that might have been better in other locations ... that didn't exist. This undermined the organizing of the content. For Fedora 10, we devised a new scheme -- major chapters that pulled the beats in various nestings using the power of modular XML files converted 1:1 from the wiki pages.
Now that we have a larger documentation base and greater need for updated content, I wonder if now is a good time for the beats to take on a larger purpose? Providing the stream of content that feeds in to all the myriad documentation. Does that pervert the usefulness of the beats to the release notes? Or rather provide a way to clean them up a bit?
For example, there is often content in the release notes that could be in the Installation Guide[1]. We maintained a long piece originally by Tommy Reynolds about building custom kernel packages, which finally migrated to the wiki and remains with a reference.[2] And so on.
There seems to be a use for filtered and unfiltered feeds of content that the Docs Project can use to populate parts of various documents, instead of just jamming it all in to the release notes. ;-) The mailing list 'fedora-relnotes-content'[3] that receives release notes reports has always provided information useful to other documents.
Lest you think I'm crazy suggesting a process change this late in the F11 release cycle, I don't think it has to be that much of a difference. More of an awareness to share with beat writers -- gather content that might have meaning beyond just release notes, and Docs will parse it to the right content home.
- Karsten
[1] http://docs.fedoraproject.org/release-notes/f10/en_US/What_is_New_for_Instal...
[2] http://docs.fedoraproject.org/release-notes/f10/en_US/How_are_Things_for_Dev...
[3] https://www.redhat.com/mailman/listinfo/fedora-relnotes-content
Receives relnotes@fedoraproject.org, release notes bugzilla reports/fedora_requires_release_notes flags, used to watch the Docs/Beats.* changes in the MoinMoin wiki, good place to send a feed of all changes to the beat pages.
----- 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
docs@lists.stg.fedoraproject.org
-
John J. McDonough -
Karsten Wade