My thoughts on release documentation

[Adam Williamson]

Hi, guys. So, I mentioned in my introduction email what I wanted to
bring up within the docs project context, and I also mentioned this at
the F11 post-release recap meeting yesterday. Here's a longer message
with my thoughts.

There's quite a lot of important information about F11 which needs to be
documented somewhere, that's coming to light either late in the release
cycle or after the release is made. I can cite multiple examples if
needed, but I won't to keep down on length - if anyone is unconvinced of
this point please ask, and I will cite chapter and verse. :)

At present, it doesn't seem like this is handled very well. There's the
Common Bugs page which I'm sort of maintaining and which can easily be
updated post-release, but that has a very specific mandate and things
which are not actually bugs fall outside of it.

Aside from that, things get messy. We end up with multiple,
non-canonical sources for this information. Some of it winds up in
things like Rahul's FedoraFAQ -
http://fedoraproject.org/wiki/Fedora_11_FAQ . Some of it winds up in
blog posts - ironically, I can no longer find the pair of posts by one
person which would have made perfect release notes entries that I was
going to cite as examples here, which is annoying but also perfectly
highlights why this isn't a good method :). Some of it winds up in
fedora forum sticky threads -
http://forums.fedoraforum.org/showthread.php?t=223206 . Some of it winds
up in little bot-automated notices that the #fedora IRC guys use. It's a
mess.

This is problematic for two obvious reasons: it detracts from the
'brand' of the canonical release documentation, meaning people take it
less seriously because they know it isn't going to cover everything, and
of course it makes it a bitch to find all of this information.

Looking at some of the previous discussion on this list, it's obvious
this has come up before, and people have been talking about ways to
address it. There seems to be a focus, however, on ways to try and make
sure all the information gets in before the release notes freeze, at
which point all bets are off.

I'm not sure this is ever going to work; I think that, no matter how
great we are are getting as much info as possible in before the freeze,
sod's law dictates there's always going to be _something_ that will come
up either shortly before release, at release time, or after.
Consequently I think the release documentation process needs to be
flexible enough to provide a canonical source of release information
that can be updated reasonably easily and quickly throughout the release
cycle, and afterwards.

I see for F12 there seems to be a proposal to split the release notes
into two - a shorter, 'greatest hits' page for 'regular users', and the
full fat thing for 'advanced users'. Would this be anything like how I
handled it for MDV? For MDV there are three main release documents, the
Release Notes, Errata (like Common Bugs) and the Release Tour. The
Release Tour is a shortish document which simply explains shiny new
features - not any problems introduced by changes, really - with lots of
screenshots and so on. See the 2009 Tour, for instance -
http://wiki.mandriva.com/en/2009.0_Tour . 

If it's going to be something along those lines, I might suggest that
the 'advanced' release notes be done with a kind of dual-track system.
We can still freeze the initial contributions to produce a nicely
formatted and translated frozen set of release notes at release time.
However, we could continue to accept changes to the wiki contribution
pages after the freeze date, and pull these together into a
quick-and-slightly-dirty 'live' release notes page on the wiki, which
could be constantly updateable through the life of a release. Well,
that's just an initial thought. The general idea is more important than
the implementation details.

If we can get something like this in place, I'd hope we'd be able to
reach out to all the groups who tend to find stuff that needs
documenting - forums, IRC, qa/bugzappers etc - and ask them to
consistently document frequently arising issues in this canonical
location, so that everyone's singing from the same hymn sheet and the
'cachet' of the canonical documentation is improved.

Hope that makes sense :) please do let me know your thoughts on this.

-- 
Adam Williamson
Fedora QA Community Monkey
IRC: adamw | Fedora Talk: adamwill AT fedoraproject DOT org
http://www.happyassassin.net