Working together on documentation (was Re: Quality Control Suggestion)

[Matthew East]

I'm cross posting this to sounder too, because I think that lots of
people who help out on irc follow that mailing list.

On Thu, 2006-05-04 at 16:23 -0700, Matt Zimmerman wrote:

{snipped - for context, this part of the thread is about the answers
given by the IRC Bot}

> I'd like to get some sort of process in place, in
> concert with the Documentation Team, to vet these kinds of answers with the
> development team before they're published to the user community as
> authoritative, and review them for each release to ensure they stay up to
> date.  Would you be willing to help with such an effort?

I think there is a really good possibility for improving the efficiency
and accuracy of answers given on IRC by the IRC team and the
Documentation team working together here. There is duplicated work going
on here in these teams, because maintaining the bot's answers, and the
documentation, is essentially doing some of the same things twice. We
can improve efficiency and reliability by doing them only once.

Here is what I suggest (and I think this is really doable by the time
dapper is released):

The bot, rather than giving answers, refers to the documentation
directly via the website. For example, if a user enquires about playing
DVDs, the bot gives the answer:
http://help.ubuntu.com/6.06/ubuntu/desktopguide/C/video.html#dvdplayback
and if a user enquires about setting up an nvidia graphics card, the bot
gives the answer:
http://help.ubuntu.com/6.06/ubuntu/desktopguide/C/hardware.html#graphics-cards

This solution would have at least the following advantages:
 * Removes the need to maintain two sources of information
 * Improves the reliability of the information (partly because the
documentation gets the benefit of work from the wiki and the attention
of the documentation team, and partly because I think focusing on
maintaining one resource will increase reliability).
 * More irc participants will be encouraged to get involved in improving
the documentation
 * It is easy to be release-specific, as the documentation website will
contain the documentation for each supported release from 5.10 onwards.

By way of analogy, the Italian team recently considered introducing an
irc bot. One of the first things that we considered was that we
shouldn't program information into the bot that already existed on our
wiki/documentation area. The reasoning was that we simply don't have the
resources to maintain both and make sure that both are accurate.

The solution would also have the advantage when doing quality control
interaction with the developers: rather than both teams having to go to
the developers for help, we would only have to go once. In terms of how
such quality control would work, I'm happy that this release cycle, this
has gone really well: the answers of developers on irc about questions
regarding information to be put into the documentation was always really
helpful, and several developers (most notably Adam) reviewed certain
sections of the Desktop and Server Guides for accuracy, which led to a
number of really good corrections. I'm not sure that a formal review
process is necessary, given the success of this, but maybe others have
some good ideas about a more formal collaboration process.

Matt
-- 
mdke at ubuntu.com
gnupg pub 1024D/0E6B06FF
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 191 bytes
Desc: This is a digitally signed message part
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20060505/ae024a7e/attachment.pgp>