My thoughts on release documentation

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