Some thoughts on beat writing

[John J. McDonough]

Now that Fedora 10 is in the box, I felt it might be useful to share some 
thoughts I had as a new beat writer, with an eye toward improving the 
process for Fedora 11.

The new beat writer is faced with three big challenges; 1) What is 
actually -IN- the beat, 2) What has changed and, 3) What level of detail to 
write about.  There are other hurdles to be sure, but these three seem 
almost insurmountable.

Geek that I am, I discovered that the answers to the first two can be (sort 
of) answered by rummaging around in the primary.sqlite files. 
Unfortunately, the PackageKit groups don't map precisely to the beats, and 
(IMO) there are a significant number of errors in the grouping, but these 
files contain the packages and their descriptions and versions, as well as 
the URL to the project.  By comparing versions between the rawhide sqlite 
file and the previous release, changes can be detected.  Once you see a new 
version the URL to the project (and sometimes the upstream's release notes) 
is right there. Unfortunately, you need to look at two different files, and 
you need to have some way to identify what packages actually are in your 
beat, so for me the path of least resistance was to import the whole shebang 
into MySQL.  Obviously, that wouldn't be the right path for most beat 
writers.  Also unfortunate that I didn't really discover this until late in 
the game, and my beats don't reflect this.  I'll do better next time.

The guidance I got initially was to follow the features pages and rummage 
around in bugzilla.  Bugzilla is too slow and too noisy to be very useful 
for this sort of exercise, and the features pages only deal with the major 
changes.  A lot of packages get updated, and although in the context of the 
entire release these may be minor events, when viewed through the microscope 
of a user of that particular package, it could be quite a big deal.  I was 
also advised to watch the commits, but I never did learn how to actually do 
this, and I suspect that would have the same noise problem as bugzilla.  I 
do watch the RSS feed on commits, but there is just too much going on there 
to pick out the relativly few I care about.

The other issue that should be addressed in the notes is the tension between 
what's there, what's changed and what's new.  I think the games guys did the 
best job on what's there.  They had a nice, short description and a link to 
a wiki page with the details.  Unfortunately, they didn't address the what's 
changed.  I suppose in principle the release notes ought to only reflect the 
differences, but we really need a "what's there" that is approachable.  The 
new user can't really make sense of 11,000+ packages, and although the 
PackageKit grouping helps some, it doesn't help enough.  Many beats are 
really descriptions of what's there, sometimes to the detriment of what's 
changed.  One interesting aspect of this is that what the new user needs has 
a tremendous overlap with what the new beat writer needs.

I'm thinking each beat needs two wiki pages.  One for what will end up in 
the release notes, and another for what is actually in the beat.  The 
release notes page could direct the reader to the wiki what's there page for 
a full description of what Fedora offers on the particular subject, but the 
release notes content should be prefaced with a (very) brief description. 
In a lot of cases, there is a need for some (sometimes a lot) of nesting of 
pages.  I'm not sure if the intent of the page renaming exercise is to 
eliminate this entirely, but for example, in Software Development there is 
Runtime and Tools, and within both there are hundreds of packages.  There is 
some very uneven hierarchy in Tools, but not nearly enough.  I hit the 
biggies on this release, but Im sure there were dozens of changes that were 
missed and that were important to someone.  Long lists of paragraphs are 
hard to navigate and hard to maintain, so some structure is needed.  This 
structure can probably best be provided by including lower level pages in 
higher level, I suspect the page names aren't all that important.  But the 
page naming thing still worries me.

At this point I now understand how I will attack Fedora 11.  I realize that 
my approach isn't particularly helpful for most people, so I won't outline 
it here, but I am noodling on how we might help future beat writers.  I 
wonder if other beat writers, especially new beat writers, faced similar 
challenges and how they addressed them.  I suspect we (maybe even I) can 
make things a lot better for future beat writers, but then maybe I'm just 
dumber than the average bear.

--McD