The Fedora Core release notes suck!

[Edward C. Bailey]

Hello all,

    OK, now that I have your attention...

I can make the claim I did in $SUBJECT because I wrote them (actually,
others have made the same claim, but I digress)... :-)

I'll be making changes in the way the release notes are done for Fedora
Core 2, but first I want to collect some data.

Basically, what do you want the release notes to look like?

Currently, the release notes includes the following sections:

    o An Introduction to the Fedora Project (Should this be kept?  Might be
      a good way for newbies to get hooked into the Fedora community)

    o Hardware Requirements (CPU, disk space, memory)

    o Installation-Related Notes (Anything that impacts the user during
      installation)

    o General Notes (Anything else that doesn't fall into any of the other
      sections)

    o Package Changes (packages that have been added/deleted/deprecated)

    o Kernel Notes (If it relates to the kernel, it goes here)

These sections came into existence organically (meaning that nobody really
thought about it :-) and I think it shows.  The biggest thing I dislike
about this structure is that the "General Notes" section becomes so
overwhelmingly large that it's difficult to find anything in there.

Some differing approaches come to mind:

    o Make it all package based

    Pros:

        - If you want to see whether package foo has anything of interest,
          it's easy enough to find out -- look in section foo.

    Cons:

        - Way too many sections with way too little content in each one

    o Make it partially package based (select which packages get their own
      section based on packages that are "important" or "big" or "changed"
      enough -- everything else goes into a "none-of-the-above" section)

    Pros:

        - Still pretty easy to find stuff (you look for a specific section,
          if nothing, look in "none-of-the-above")

    Cons:

        - How to select which packages get sections in a meaningful way and
          with a minimum of flames ("Hey, why didn't 'foo' get a section --
          it's really important/big/changed?")

    o Make it based on function (for example, "Desktop", or "Programming")

    Pros:

        - If chosen well, sections would make sense

    Cons:

        - While most packages would be easy to categorize, there will
          always be ones that might straddle sections -- what then?  And
          there's still probably need to be a "none-of-the-above" section,
          though it should be minimal in size (if the functions are chosen
          well)

My instinct says a function-based approach would probably be best, but
maybe someone out there has an entirely different approach that would be
even better.

In any case, I'm sure that I can't do as good a job coming up with ideas as
everyone reading this. :-) So, let's hear it -- what do you want the
release notes to look like?

                                Ed
-- 
Ed Bailey        Red Hat, Inc.          http://www.redhat.com/