>>>>> "Felipe" == Felipe Alfaro Solana <felipe_alfaro@xxxxxxxxxxxxx> writes:
Felipe> On Mon, 2003-11-24 at 22:54, Edward C. Bailey wrote:
...
>> o Make it all package based
Felipe> This is the one I prefer:
...
>> Cons:
>>
>> - Way too many sections with way too little content in each one
Felipe> I don't mind if the document is big: it's a digital document and I
Felipe> can easily browse/search through it.
That's not really the issue -- the issue is that it become more difficult
for different kinds of people to find something given this kind of
structure, particularly if you don't know what package(s) to look for. We
need an approach that works well for people that know what package they are
interested in as well as for people that don't.
Felipe> I always expect the Release Notes to be as detailed as possible,
Felipe> even if the file is several megabytes long ;-)
I apologize to Felipe for hijacking his email for this purpose, but I think
it's time for a "facts of life" conversation... :-) It's something I knew
I had to do at some point anyway.
Ok, first a bit of history -- here's how the Red Hat Linux release notes
were produced.
The RHL release notes were, for the most part, written by one person.
This has always been a part-time job; I'd estimate that the RHL release
notes took up maybe 10% of my time. Maybe. By far the bigger part of my
time was taken up with writing content for manuals, or preparing to write
content for manuals (testing new software, writing outlines for new
chapters, etc.) No, it's not the best possible situation, but it's the
only situation available... :-}
The content for release notes came from a number of sources:
o The engineers themselves ("Hey, I just put in a new version of
'foo', and it now has support for 'bar' -- you should mention
that")
o The beta testers ("I can't believe you don't mention 'foo' in the
release notes -- you should put it in there before you go gold')
o Personal experience playing with the betas ("Hmmm, now *that's*
going to confuse somebody -- I'd better write that up")
o Holdovers from prior release notes (The Ximian GNOME entry, for
example)
This list is in no particular order as to priority (all sources were given
the same priority ranking) or the amount of contributions from each
source. But it shows the basic manner in which the release notes were
written.
It also points out flaws in the system. For example, if an engineer
forgets to tell me that some important change has been made (a likely
occurence, as every engineer is responsible for many packages, and is just
as overworked as I am), it will only get caught if a beta tester (or I
personally) catch it. Ever wonder, "why on earth didn't they mention
*that* in the release notes"? This is most likely the reason.
In a perfect world, engineers would always remember. Or, better yet,
there would be an automated way to capture important changes (neglecting
for a moment the problem of funneling the information for nearly 1500
packages down to one person in an easily-digestible form.)
The other thing to keep in mind is how the RHL release notes fit into
the greater scheme of things -- particularly with respect to the other RHL
documentation. The release notes were never meant to be any kind of
standalone document; instead, they were intended to capture stuff that met
one of the following guidelines:
o Information so vitally important that it warrants being mentioned
in the release notes *and* in the appropriate RHL manual(s).
o Information that came to light so late in the development process
that it could not possibly be added to the appropriate RHL
manual(s) in time for the gold release.
Every attempt was made to move all appropriate stuff from the release notes
to the appropriate manual(s) after the release went gold. Yes, sometimes
we've blown it; other times there has been no appropriate "landing" place
in the manuals. And don't get me started on pagecount limitations (unless
you point me at a drinking establishment and are buying for the
evening)... :-)
Ok, so that is the history. With all this in mind, let's move forward
to the present. What ends up changing in the Fedora world? I can think of
a few things:
o The community of "beta testers" is *much* larger than before,
hopefully making it much more difficult to overlook something
that the engineers forgot to mention
o Since the process is much more open, it should be possible to put
out release notes much more often (with RHL, the new versions of
the release notes got in front of beta testers eyes with each
beta release: maybe 3-4 times at most)
o There are currently no other supporting documents for Fedora
Core, meaning that the release notes might have to take up a bit
more of the slack than was previously the case (although people
are starting to work on documentation projects, so this might not
be a long-term situation)
The main thing that remains unchanged is that my time for Fedora Core
release notes is likely to remain more limited than I'd like. However,
this may not be as much of an issue as it might at first seem. For
example, I can imagine that eventually there will be people in the
community that will be able to take on the role of contributing writer for
the release notes. I am also working on a way of making the workload scale
more easily. More on this later.
All this is an admittedly long-winded way of helping people understand
the environment in which the release notes have been written, how I expect
the process to change, and that Felipe should not expect multi-megabyte
release notes just yet... :-)
Ed
--
Ed Bailey Red Hat, Inc. http://www.redhat.com/
