External review of the doc writing process
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