The Fedora Core release notes suck!

[Axel Thimm]

On Mon, Nov 24, 2003 at 04:54:49PM -0500, Edward C. Bailey wrote:
> 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?

The current release notes do not suck ;)

I think there are three kind of audiences for release notes, first time
users, upgraders from the previous release and release lawyers that
need every changed detail documented ;).

Upgraders could probably need a more explicit Changes section,
e.g. they know the hardware requirements and installation steps of the
previous release, so all they want to know is what changed in these
sections and what changed in the content, but probably from a rather
global POV than at a package level.

First time users need the release notes as they are today. The most
important sections are at the top and they will not care much about
differences to previous releases.

A functional approach of changes seems most appropriate, if yet
another package detailed view is needed it should be outsourced into
another document to keep the base release notes compact and readable.

I'd split the release notes into two parts

o first time use (assuming novices)
  - Introduction (referring upgraders to the changes doc)
  - Hardware
  - Installation (no upgrade instructions, refer the reader to the
      changes doc)
    - Postinstall notes for new installations
  - non-intuitive specialities found in this release
    - additional kernel features
    - other non-trivial features

o upgrading/changes (assuming semi-veterans ;)
  - General changes compared to previous release
  - Noticable hardware requirement changes (if any)
  - Noticable installation changes (if any)
  - upgrade instructions
  - package changes

But the release notes still don't suck ;)
-- 
Axel.Thimm at physik.fu-berlin.de
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.fedoraproject.org/pipermail/users/attachments/20031125/0b2ad25a/attachment-0002.bin