Proposal: Create product for each derivative's documentation

[Emma Jane Hogbin]

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.

Disclaimer: It's late, I just finished an eight hour drive and I'm
looking forward to sleep. Which means you'll get the real answer in the
short and sweet version.


As a team, we suck.


1. The tool chain too hard for new contributors.
2. The "team" is highly controlled by a very few number of people.
3. There is no ongoing critical thought around our effectiveness at:
	- producing useful documentation; and
	- increasing participation on the team.


And here is the expanded version of each of these points:
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.
I edit DocBook by hand with Vim and have since at least 2003. I write
XSLT transformations by hand in Vim. I have installed a custom toolchain
for producing PDF documentation from DocBook XML using FOP (which I
compiled myself at the command line). I have converted DocBook XML to a
related DTD which allows you to generate HTML slides for presentations
from DocBook. I use Bazaar from the command line, comfortably. 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.

Aside: The wiki is great and I have made more than a few edits using it.
But the official documentation uses its tool chain as a barrier to
participation.

2. As far as I can tell very few of us have been "trained" in technical
writing. Several of us are published authors and many of us have a lot
of experience writing technical documentation, but 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!

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? 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

Documentation is *not* code. Launchpad, Bazaar and Rosetta do not deal
with documentation elegantly. They are tools that were designed to work
with code. We happen to be using text-based XML files so it works, but
it is not elegant. We can build the tools to suit our needs. I know this
may sound crazy but we're a darn clever bunch and whatever we can
imagine, we can build!

As Belinda mentioned in a previous email, FLOSS Manuals is doing cool
stuff with a Wiki and sprints [2]. Drupal was granted $50,000+ to run
documentation sprints over the next year--including a meta sprint [3].
Drupal also has monthly challenges to help people identify low hanging
fruit. Even the Linux Documentation Project now has a Wiki version of
its articles for editing purposes [4]. There are innovative things
happening in the world of documentation, and new code is being generated
to deal with the next wave of documentation [5],[6].

[2] http://flossmanuals.net/
[3] http://rocktreesky.com/different-kind-doc-sprint
[4] http://wiki.tldp.org/
[5] http://groups.drupal.org/node/20127
[6] http://en.wikipedia.org/wiki/Wikipedia:WikiProject_Wikislice

Ubuntu is innovative. Usability and "user experience" is the new "hot
topic" (it's awesome that the open source code is now mature enough that
UX is at the top of the list) Documentation is part of the user
experience. Let's figure out how to provide an amazing experience for
everyone using Ubuntu...and maybe figure out some best practices for
single sourcing documentation along the way. :)

</rant>

regards,
emma

-- 
Emma Jane Hogbin
https://wiki.ubuntu.com/EmmaJane
https://launchpad.net/people/emmajane