Jargon Buster wikification

[Karsten Wade]

On Sat, 2006-11-18 at 17:17 -0500, Paul W. Frields wrote:

> I like the idea of more contributions to the glossary.  It's a worthy
> goal.  I just wish that, at the same time as we get more contributions,
> we were also encouraging people to submit the changes in a more
> automatically trackable way.  That way is Bugzilla.  (I'm reminded that
> random people can't contribute to our wiki -- they have to go through a
> series of steps (you've done them, of course) including the CLA.)
> 
> Wiki notifications are a fine way for anyone currently using the wiki to
> pick up "what needs to be done."  But what about John Newuser, who just
> joined?  He starts at square one, and even if he has CVS and DocBook
> skills, and is well-informed enough to turn on all his notifications
> immediately, he will have no idea what entries need to be moved.  He
> can't get backdated notifications.
> 
> Bugzilla is a queue of problems that any motivated contributor can
> consult for a "to-do" list.  John Newuser can look at the list, pick a
> problem, and get down to business.  Bug and task tracking tools are the
> ideal way to capture this work, and produce other useful information
> like how long it's taking to get them closed or handled.  The wiki
> satisfies none of those needs, unfortunately.
> 
> Again, I'm not blasting use of the wiki -- but it's very clear to me
> that it's not a sustainable and valuable tool in the way that SCM and
> Bugzilla clearly are.  It's merely good for collecting raw material
> quickly.

I've been watching release notes in particular be produced for the last
three+ years, internally for RHEL, then externally in Fedora.  To be
honest, bugzilla was always a bit of a barrier that even seasoned
developers wouldn't overcome unless the error was egregious or the new
content valuable.  I'd see poor Ed begging for input time after time,
and only a dozen developers actually put anything in the bug report.

This is in stark contrast to what we've experienced with the Wiki.  At
least two to three times the number of developers have helped with
content and reviews, and it's easier for people to dig their hands in
and get stuff done.

What I'm thinking is that bugzilla can work for all levels, but there is
a granularity level below which input decreases.  For example, more
reports are filed for technical errors, while translation and
grammar/spelling errors get few bug reports.

Also, there are other ways to leave a trail in a Wiki that helps tell
other authors what needs to be done.  Comment blocks for example.

Perhaps there is a level we can identify where some things belong in
bugzilla and some stay in the Wiki.  For example:

i. Master bug tracker has a number of task bugs it depends on

ii. Task bugs specify e.g. "Finish kernel section of relnotes for FC7"
    - Task bugs can have any number of notes that show status or have
discussions on various parts
    - Task bugs can be trackers for other related bugs, such as
requesting a review of a piece of content from a kernel developer; open
a bug for the review, it is closed when the review is done.

iii. When writing in the Wiki, a page author *must* keep a status
checklist of "Task to be completed" within the Wiki page.  It could be
in a comment block at the beginning/end, or a special section that is
appended to the end and only erased when all is completed
     - This gives an ongoing status of that page
     - Anyone who comes in to help instantly knows what needs to be done

iv. We specify what deserves a stand-alone bug report (use a template
for it) and what should be added by someone to the in-file status
checklist.

Questions:

a. How much of this should really be Plone workflow?
b. This is a fair level of process, can we enforce it?  Can we teach it?
c. Does this address the appearance of bugzilla as a barrier to getting
work done?
d. What other items are now in bugzilla that we can use for this?
   - Notice the new Flags: 'requires_release_note' ?
e. How about the new CVS pre commit hooks that grab what BZ is fixed,
etc.?

Bottom line is this:  if the only way to get a change in e.g. Fedora
Glossary is to file a bug report, we will receive 1/10th to 1/100th the
number of fixes and entries than if we put it in the Wiki for editing.
We have to balance the challenges of Wiki -> XML with the increased
contributions.

Perhaps for some things, we should just have the Wiki expose the raw
XML, which it can right now (AIUI).  Sure, it forces people to make
changes in actual XML, but they do it with the perceived ease of a Wiki
edit.

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061119/8f0e0020/attachment.sig>