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
--
fedora-docs-list mailing list
fedora-docs-list@xxxxxxxxxx
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list
