Re: Gnome 3 and Documentation

[Matthew East <mdke ubuntu com>]

Hi Shaun,

On Mon, Apr 6, 2009 at 8:29 PM, Shaun McCance <shaunm gnome org> wrote:
> What Documentation We Need
> ============================================================
> It's very important that we have a replacement for the aging
> user guide.  A new user guide is our opportunity to showcase
> what users can get done with our desktop.  Without a new user
> guide, we risk alienating lots of potential users.

I would tend to go a bit further, and say that we should stop talking
about a user guide for Gnome at all. The concept of an all-consuming
guide doesn't fit very well with the "task based help" approach which
you've (rightly) propounded elsewhere in your email.

By way of comparison, we used to have a single all-consuming "desktop
guide" in Ubuntu help. We gradually realised, with the help of Matthew
Paul Thomas, that a "guide" this was the wrong way to look at desktop
help. This led to a breakup of our documentation into separate
categories, and a change of emphasis from a complete guide to
different help pages.

The move is documented here: https://wiki.ubuntu.com/TopicBasedHelp

This may be a linguistic distinction, but I think it's quite important
for how we look at documentation and the task that Gnome faces as an
upstream provider. It's key that the documentation that is produced
upstream offers extreme pluggability so that distros can easily drop
material into the structure provided by upstream to cater for the
situations where they customise and add to the Gnome desktop
experience.

I know that you've very aware of this need because it is central to
the Mallard design, but I wanted to get this thought out there.

> Task-Oriented Documentation
> ============================================================
>                       "To open a file, choose File ▸ Open."
>
> Our current documentation reads like stereo instructions.
> When they have any real information at all, it's either
> purely descriptive of the interface or a regurgitation of
> the internal design of the software.  The documentation
> isn't designed to teach anything.  We have no plans, so
> we just pour everything we know into DocBook.  Too much
> information gets in the way of learning.

This is true, of course. And I agree that teaching is an essential
part of what the documentation should do. However, it's a reality that
a lot of computer users really do need walking through the buttons
they need to press when performing a particular task, and that when
they learn how to do it the first time, they quickly forget. So I'm
sympathetic to documenters who make an effort to specify the exact
buttons that need to be clicked, and I think that a middle ground
needs to be struck.

> If we could get a a build team together to produce virtual
> machine images of vanilla upstream Gnome, it would be very
> helpful.  We need these sooner rather than later.  Writers
> need to get involved earlier in the development process,
> and we need our developers to be responsive to writers.

Just to reiterate the importance of this - this is the sole reason why
I haven't contributed more to Gnome documentation. I'm worried that a
patch I produce will be inaccurate because Ubuntu customises Gnome in
particular ways, and a way to run a vanilla Gnome build (even in
VirtualBox or another VM) is absolutely essential.

> I think the best way to get started is for me to have a
> small crack team that lays the groundwork with me.  We
> would work closely together, sharing our knowledge and
> experience.  These people could then help me in training
> new contributors and communicating with our development
> teams.

I'm in and will do what I can. As others have said, a roadmap is
essential. For example, if Mallard will be implemented within 3
months, then the approach will be very different to the approach
needed if Mallard won't be implemented for another 9 months, or at
all.

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