Proposal: Create product for each derivative's documentation

Thu Apr 9 10:10:39 UTC 2009

There's an interesting point in there about the Wiki team. Shouldn't
wiki-team members have some elevated responsibility such as making
pages immutable, deleting etc.

The reason I ask is because if we look at the system documentation as
a Swan - its graceful and purposeful on the visible portion but going
like the clappers underneath. We have six months to redefine,
consolidate and revamp something which will most likely be a great
product.

I still see the biggest area needing improvement as the wiki - huge
numbers of pages are needing deleted and a lot of tagged pages needed
to actually have the tagged actions carried out.

So just to toss another iron in the fire - are we happy with the
wiki-team structure? Should core-doc extend to certain rights over the
wiki? Then the wiki-team badge can become a little medal for
contributing.

The waiting list is silly too - I was on that list so long, the
application fell off!

2009/4/9 Matthew East <mdke at ubuntu.com>:
> 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
>
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>

-- 
Regards,

Dougie Richardson
http://www.lynxworks.eu/
dougierichardson at ubuntu.com