Hey, folks. I thought you may be interested in some comments on the release documentation process and Docs wiki area which Christopher Beland happened to write up - the context was QA group reviewing how we document the process of having issues added to Release Notes / Installation Guide / Common Bugs. It may provide ideas for improvement :) Chris wasn't trying to bash the docs process, he just happened to take a look at it while looking into this issue for QA and make a few comments. ---- The Release Notes are maintained by the Docs Project, which I'm not a primary participant in. Their wikispace is a mess; there are a lot of obsolete pages that need to be cleared out, and current information that needs to be more cleanly organized. The release notes are pretty clearly the place for announcements about changes, and they get written mostly from scratch each cycle. https://fedoraproject.org/wiki/How_To_Contribute_to_the_Release_Notes lists "Six Ways of Submitting Content" which seems a bit crazy. I've not had much success (I think this was between alpha and beta) using the "Beats" process in the wiki, which are supposed to be rolled into release notes. I would really expect to see one page in the wiki somewhere that represents what the Fedora 13 release notes are going to look like, but right now there's just stuff from Fedora 12 marked as "this is final and has been sent for translation". What's actually *in* the Fedora 12 release notes is similar, but clearly a lot of editing has happened between the time it was taken from the wiki and the time it was released. I'm also not confident that methods that involve sending a message to a mailing list are reliable; Bugzilla reports are much better at persisting until someone actually deals with them. There are actually three release note issues in any given release cycle - alpha, beta, and final - each of which to me should build smoothly off the previous issue (adding new notes and deleting obsolete ones). It seems like in an ideal world, these would just live in the wiki, and at the appropriate times in the schedule, get translated and rendered into HTML or XML for publication on the web and in RPMs. Right now, I'm not confident that anything I put in the wiki would get added to the release notes, so I just file reports in Bugzilla and let the Docs team deal. This also seems to be the only way to change release notes after they've been finalized. Which might not be a bad thing, since you think there should be a high bar to changes at that point, but if that's the best route, it's probably best that the documentation reflect that. All of the other guides (Installation, SELinux, Deployment, etc. at http://docs.fedoraproject.org/) also seem to live in a version control system off-wiki, which if you ask me tends to create a bottleneck and discourage random people (like community QA participants) from contributing. A wiki, after all, is just a version control system that manages formatted text in a very user-friendly way. When documents are off-wiki, that also encourages the growth of redundant content in-wiki, which attracts attention and updates, further starving the off-wiki version of contributions. I suppose if the content must remain off-wiki for whatever reason, this could be avoided by squashing these redundant documents and leaving placeholders admonishing potential contributors to file bug reports against the off-wiki documentation instead. It seems right that bugs aren't mentioned in the guides or release notes, as that helps reduce clutter and centralize fast-changing information. Major bugs are fixed before release, and minor bugs are documented online in Common Bugs or Bugzilla, since the status of fixes and workarounds is dynamic. If the slow-changing documents all link to Common Bugs, that should work pretty well, unless you think people without network should have access to "known issues" in their copy of the distribution. That could be fixed by including a snapshot of "Common Bugs" in the fedora-release-notes RPM. There doesn't seem to be much point in updating it after the release except for re-spins (which are unofficial). If you don't have network access, the original version is accurate because you haven't gotten any updates. If you do have network access, you should get the online version, and so the RPM version would need to have a line at the top that says "This page was generated on [date]; for the latest known issues, workarounds, and fixes, please see [url]." ---- Full post: http://lists.fedoraproject.org/pipermail/test/2010-January/088137.html -- Adam Williamson Fedora QA Community Monkey IRC: adamw | Fedora Talk: adamwill AT fedoraproject DOT org http://www.happyassassin.net -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
