Re: Gnome 3 and Documentation

[Shaun McCance <shaunm gnome org>]

On Wed, 2009-04-08 at 17:53 +0100, Matthew East wrote:
> 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.

Actually, I disagree.  I think you're averse to the term
because we've been using it wrong for a long time.  When
I think of a guide, I think of somebody I hire to show
me around a city.  She doesn't just rattle off everything
she knows and send me out on my own.  She gives me useful
suggestions and answers my questions as they come up.
The more we can make our documentation like that guide,
the better off we'll be.

I would argue that, document titles notwithstanding, we've
never actually produce any guides.  We've only ever made
manuals.

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

Absolutely true.  One could write an entire chapter of
a book on knowing your audience.  In an ideal world, we
could have topics tailored exactly to every user's skill
level and learning style.  But nothing short of that
hypothetical human guide is going to accomplish that.

Getting the level of information right is an incredible
balancing act.  If you fill it with too much hand-holding,
more experienced users will be frustrated and unable to
use the documentation well.  If you fill it with too much
conceptual information, beginners' eyes will glaze over.

If you look at the commercial publications sector, you'll
see a wide variety of books on the same subject.  These
address different skill levels as well as different
learning styles.  We can only do so much on our own.

Sometimes it comes down to a numbers game.  When you can't
do everything, you do what will be the greatest benefit to
the greatest number of users.

--
Shaun