https://help.ubuntu.com/community/Software/ProjectHome

[Matthew East]

Hi,

On Wed, Aug 6, 2008 at 8:32 PM, Duncan Lithgow <dlithgow at gmail.com> wrote:
>> and discuss your ideas on the documentation team
>> mailing list (cc'ed).
> <may offend>Sort of. I don't feel that the documentation team should
> take ownership of the Community Documentation. Encouraging activity
> and participation and improvements on a wiki is not the same as
> coordinating official documentation. A wiki should be allowed to
> evolve naturally. Trying to tell people all the time "Don't do it that
> way" just kills their interest. I think many pages on the wiki an
> examples of great starts that never got further.</may offend>

You're sort of right. I do understand your concern that a wiki should
be open to contribution. And this one is. However, it's not a free for
all. It needs established guidelines and a coherent team of editors
who are working according to sane principles. All successful wikis
that I'm aware of have that.

The documentation team is responsible for those guidelines and for
discussing those principles. That doesn't mean that we use the same
processes on the wiki that we do with the official system
documentation, of course we don't - the processes we use on the wiki
are adapted to the fact that it is based on open contribution. But
it's not a free for all.

> I'm waiting to hear back from the list admins about why I'm not
> getting mail from ubuntu-doc.

As I mentioned to you on irc the other day, I checked your account
configuration and there is nothing wrong with it. I suspect your
problem must be a delivery issue either with your provider or the
Ubuntu email provider. In the latter case you'll need to contact the
Canonical sysadmins to debug the issue at #canonical-sysadmin. Anyway,
I'll copy you in to emails on this thread.

>> Also, it overlaps in content rather heavily with
>> https://wiki.ubuntu.com/HelpWikiQualityAssurance (especially the stuff
>> about page banners). I'm concerned to see that you've gone ahead and
>> transferred your own ideas about page headers and other ideas directly
>> to the wiki guide at
>> https://help.ubuntu.com/community/WikiGuide/PageHeaders rather than
>> discussing them with the documentation team first. Had you done so, I
>> would have certainly encouraged you to contribute to the discussion
>> around HelpWikiQualityAssurance and to help implement that
>> specification.
> See my comments about the nature of a wiki. <may offend>Too much talk,
> was time to do something and I had a week spare. The age of that
> discussion should itself be an indication of the success of such
> prolonged ruminating about ideal solutions. A wiki is hard to break
> and quickly repaired. The vast majority of pages have so few
> relationships with each other that any structure is an improvement in
> my opinion.</may offend>

I agree that the HelpWikiQualityAssurance needs a push to get
implemented, and I understand that it can be frustrating waiting to
see something like that implemented. However, the solution is to help
it get implemented, rather than to implement your own similar solution
without discussion first.

>> The WikiGuide page is for implemented and approved
>> ideas, not ideas which are still in the process of being developed and
>> discussed. For that reason, I've removed the links on the WikiGuide
>> page until the ideas can be properly discussed and finalised.
> I will then reinstate that link, a wiki is an evolving website, not
> one bound by deadlines and procedures. The type of website suited to
> 'implementation of approved ideas' which have been 'properly discussed
> and finalised' is the online version of the Official Documentation.

No, you're wrong about that. The WikiGuide page and its subpages are a
statement of the guidelines that anyone editing the wiki should follow
and apply. For that reason we need to ensure that they are consistent
and it's not helpful to have "RFC" or "still in discussion" ideas
there about how people should be editing the wiki. I've reverted your
change, please don't reinstate it again.

I think I've been pretty clear on this so far, but just so that you're
not under any illusions: I'm *not* discouraging your ideas or trying
to exclude them, I'm simply asking that you discuss them with the team
and preferably integrate them with the team's existing ideas on the
same subject before they are put "out there" as part of the wiki's
policy guidelines.

> And those pages are very good at what they are there for: a
> structured, formal documentation site. A wiki is an evolving loose
> structure of user content, not a "did you get permission to do that!",
> "not like that!", "check your punctuation before you click save!" kind
> of place.

As I've said above, I agree that the purpose of a wiki is to encourage
collaboration. And in relation to documentation pages, we do that. But
the WikiGuide page is in a different category, that's a page which
provides guidelines to editors of the wiki, and for that reason it
shouldn't be a place of brainstorming, but treated more carefully.

>> I'm pleased to see you (and others) coming in with ideas for improving
>> the help wiki, it certainly needs those ideas and people willing to
>> contribute, but we need to make sure that contribution is channelled
>> in the right way and doesn't overlap with existing projects. I'll be
>> happy to work with you to make sure that is the case, and look forward
>> to hearing your thoughts.
> Hmm, I don't know. All the wrong alarms go off for me when I read "we
> need to make sure that contribution is channeled in the right way"
> without an explanation of who defines what's right. I'm kinda tired of
> trying to explain what needs doing when there's almost no-one actually
> willing to implement any of it. Sometimes a bit of action is good to
> shake things into life. And really we agree on so much can't just get
> on with it? Can't we share a bit of trust instead of pulling out the
> rule books?

I'm happy to see action, definitely. But some action requires
discussion first in order to ensure that it is in the right direction
(and, since you've queried what I mean by "right", I mean the
direction that is established by a consensus of interested parties
after discussion of the relevant issues). Let's not reinvent the
wheel, we have a great spec there in HelpWikiQualityAssurance, let's
focus together on implementing it.

> I look forward to starting to receive list emails when I've sorted
> that little email problem out. For now I'm going to keep cleaning up
> the bits I've started and better integrating what I've written with
> existing content.

Thank you, that's appreciated.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF