Proposal: Create product for each derivative's documentation

[Matthew East]

Hi Ema,

On Thu, Apr 9, 2009 at 5:51 AM, Emma Jane Hogbin <emmajane at ubuntu.com> wrote:
> Dougie Richardson wrote:
>> If Emma is reading this (I know she's travelling around at work) I'd
>> love to hear her experience in sharing code across branches in bazaar
>> is because what she doesn't know about bazaar isn't worth knowing.
>
> Ha! Alright. I've been tagged.

Well, if you read the bit you've quoted, Dougie was inviting you to
share some ideas about how we could use bazaar better to share
material between the different flavours of documentation we put out.
If you have any ideas about that, they would indeed be very useful.

Anyway, you've made a few points on other subjects, and constructive
criticism is always valuable, so let's discuss them, too.

> As a team, we suck.

I think that this is grossly unfair. I've waited a bit before
responding to this and have thought about it quite a bit so that I can
test whether I really do think that, or whether I'm just reacting to
the criticism, but I still think it's unfair. It's easy for you to
respond to that by saying "Matthew is biased and/or short sighted
because he is too heavily invested or involved with the current
workings of the team". And if you think that's true, go ahead and say
so. But I don't think it is. None of us want to produce bad
documentation, none of us want to exclude valuable contributors from
the team, and all of us are genuinely interested in ways that our
processes can be improved. We've evaluated them quite a few times over
past release cycles, and we'll keep doing so.

I'll explain why I think you've been unfair below in response to your
individual criticisms.

> 1. The underlying tone is, "if you can't figure it out, you're not smart
> enough to participate." And I think that's a horse poo attitude to have.

That isn't actually the underlying tone. If you reread our base page
for the system documentation, you see this phrase:

"In order to contribute to the system documentation, you need to know
a bit about the tools and processes the team uses to maintain the
documentation. Don't worry if you don't know any of our tools yet.
They are very easy to learn and it's possible to make useful
contributions before learning how to use all the tools."

That's not just a fanciful bit of positivity: it really is true. And
we've worked extremely hard on ensuring that that page and the pages
that follow it explain clearly for anyone who wants to contribute how
they can do so. No doubt improvements can be made, and if you think so
please put some proposals forward. But in any event, I don't think
there is an insuination that you need to be smart or have any
particular skills to figure out how to contribute to Ubuntu
documentation.

> So when I
> tell you that our toolchain is too hard, what I'm really saying is that
> it is completely unacceptable for us to force potential contributors to
> learn our current "official" tool chain.

It's obviously true that our toolchain is not as easy as editing the
wiki or a document with no markup. It's obviously true that in an
ideal world, it would be easier to contribute directly to the system
documentation. However, the tools are possible to learn if someone
wants to do so. We've seen plenty of evidence of that. I genuinely
believe that no special technological skills are necessary to
contribute. I myself have no training at all in computers, and yet I
found that when I tried to learn how to contribute, it was actually
pretty easy. Many other contributors are the same.

Now, and this bit is very important, I'm not saying our tools are as
easy as they should be in an ideal world. They aren't, and they *do*
constitute a barrier to entry for some people. However, there isn't
any acceptable alternative at the current time. You've said elsewhere
in your email that it is possble to create new tools which will make
things easier. That's simply not the case, unfortunately. We have
consistently looked out for better tools, for ways to export xml from
the wiki, for ways to replace xml, and despite significant amount of
work from some very clever people, they haven't yet been created.
Don't forget, xml is the markup used by two of our upstreams, Gnome
and KDE, both of whose documentation and help viewers we use and rely
on. Theoretically, Xubuntu could move away from xml as it doesn't rely
on its upstream for documentation or a help viewer, but that would
result in it losing the benefit of being able to share material with
Ubuntu's documentation.

There is some hopeful work going on in Gnome to build better tools.
Project Mallard (http://live.gnome.org/ProjectMallard), which has been
vapourware now for several years, may in fact materialise in time for
Gnome 3.0. That would allow us to reevaluate our toolchain
(potentially for all flavours). But at the present time, we simply
can't.

If you do know of solid tools that the team could use to improve its
toolchain, and have some concrete proposals to put forward that could
be evaluated, please put them forward.

In response to your allegation that we "force" people to use the
toolchain, that's not actually true either. We go to quite some effort
to point out on our team pages that valuable contributions can be made
by proof-reading, filing bugs, contributing suggestions directly to
the mailing list, editing the wiki, and so on.

> But the official documentation uses its tool chain as a barrier to
> participation.

Even if we could do something about our toolchain, the insinuation
here that the toolchain is *intentionally* used as a barrier to entry
is absurd. I don't know if that's what you are saying, but it sounds
like it.

> there is absolutely
> no reason why this group needs to be a top-down group "controlled" by an
> elite number of people. Most of the time I'm not even sure what
> "core-team" means. Was there an election? How do you become a member of
> the team? On Launchpad the most "open" team is moderated and 70+ people
> are waiting to be granted entry. The rest appear to be restricted. Good
> grief, folks! Documentation is supposed to be the fun and inclusive and
> an "easy" thing to participate in. Stop putting up artificial barriers!
> People like joining teams, so let them join!

With respect, this is no way to run any kind of serious community
team, and I've seen a lot of teams grow up in the Ubuntu community, in
lots of different areas.

Open teams quickly become overcrowded and full of people of two types:
(a) people who join with good intentions but don't end up
contributing; and (b) people who join because they are collecting team
memberships and want to be in as many teams as they can.

This works fine for teams which are essentially fan clubs, i.e. teams
the membership of which doesn't imply any special permissions. But
that isn't the case with most Ubuntu community teams. In particular,
membership of ubuntu-core-doc implies the right to modify the
{k,x,ed}ubuntu-docs package which appears in Ubuntu. As a basic
starting point, that means that people in it can change the
documentation that millions of people see on their Ubuntu system. In
extreme (and much rarer) cases, it means that people in it can
introduce bugs in Ubuntu which could lead (if not checked) to broken
upgrades or error messages when starting the Ubuntu help program. That
can't be an open team. We need to have quality control of some kind.

There is an element of truth in what you've said about the 70+ people
waiting for entry to the wiki team group. I do think we need to
reevaluate our use of the ubuntu-wiki and ubuntu-doc-students groups,
because neither of these are serving any concrete purpose at the
moment. Membership of the team doesn't entail any particular right or
permission. If that remains to be the case, we might as well have them
as open teams and let people collect memberships by joining them.

As for your question on how to join ubuntu-core-doc, the answer is
documented here -
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Submitting.
I'll paste it:

"After you get used to DocBook, bzr and the DocumentationTeam, you are
very likely to be offered an account so that you can write to the
repository as well."

Basically, you contribute some patches. Maybe we could document that
better, and maybe we could do better at encouraging people to apply
for the team. As I said, there are always things we could do better.
But arguing that we should remove quality control entirely just won't
fly.

In any event, I don't think that the way that we structure the
Launchpad team permissions is going to fundamentally change the number
of contributors we get. I think the keys are the ease of the tools
(see above), the quality of our internal documentation, and publicity
about the team.

> 3. Where is the road map for this team? How often is it evaluated? And
> why don't we have regular meetings to discuss not just documentation but
> also the meta issues of participation?

Ok, this is a valid point and is discussed on a separate thread.

> Stop moaning about the way
> Launchpad works and start telling me about your vision for this team and
> how all the components can work together! Single sourcing was mentioned.
> This is really specific and REALLY cool [1]. We should be looking at
> ways to share what can be shared, and delta what needs to be different.
> Vision first. Tools second.
>
> [1] http://en.wikipedia.org/wiki/Single_source_publishing

Again this is the subject of a separate thread and I'm sure the team
would be interested in any concrete proposals that you have. There are
quite a few difficulties that we face in applying this concept to our
particular subject-matter.

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