The Fedora Core release notes suck!

Edward C. Bailey ed at
Mon Nov 24 21:54:49 UTC 2003

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

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

    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


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


        - 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)


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


        - 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")


        - If chosen well, sections would make sense


        - 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

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 Bailey        Red Hat, Inc.

More information about the fedora-list mailing list