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

Some thoughts on beat writing

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.


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