Re: quo vadis, docs

[Shaun McCance <shaunm gnome org>]

On Tue, 2009-02-10 at 16:22 +0900, Davyd Madeley wrote:
> On Mon, 2009-02-09 at 21:37 +0000, Matthew Paul Thomas wrote:
> 
> > More good news: That's also often unnecessary. A description of a 
> > feature in checkbox-by-checkbox detail is just as boring to read as it 
> > is to write. Instead, think: What are the most likely reasons someone 
> > will have trouble here? And what things are people most likely to be 
> > looking for under a different name? Answer those questions (without 
> > phrasing them as questions) in two or three paragraphs each.
> > <http://tinyurl.com/clrt3o> Do that, and you'll have something more 
> > readable and more useful than ye olde Gnome Application Manuelle V2.7.
> 
> Matthew is right on here. Element by element UI description rarely do
> anything to help the user.
> 
> Instead I like to focus on "task oriented" documentation (opening a
> file, making changes, saving a file, making a backup). Try to group
> related tasks into sections, and try to put them in an order that the
> user is likely to need them in. Cross reference to more in-depth
> discussions if required. Include sidebars with information to educate
> and empower the user, using analogies and objects they can relate with.
> 
> Your documents can still atrophy as buttons and labels change names and
> marks drawn on UI screenshots no longer resemble the current UI, but a
> lot of the prose will still be relevant and ideally even useful.

As I've said before, I don't disagree, but I don't think
this is necessarily an either/or situation.  To relate to
all the programmers here, this is analogous to having both
tutorial-style documentation and API documentation.  Both
have value.

There are times when I'm looking at a document and thinking
"What the hell does that option mean?"  Arguably, this is
often an indication that the dialog needs some attention,
but sometimes there really is just some prerequisite domain
knowledge you can't get around.

An example off the top of my head, because I've reviewed
patches for it recently (thanks Matthias):

Currently, the Network Proxy Preferences documentation lists
all the controls on the dialog.  It tell you to put the domain
name of an HTTP proxy in the HTTP Proxy field, etc.

Assume I've gotten to this help page because I clicked on the
Help button in the dialog.  One of the following is probably
true:

1) I know I need to enter some proxy settings.
2) I can't connect to the Internet, and I'm futzing around
   with any network settings I can find.
3) I'm one of those people who explores preferences to see
   what I can do.

So this page needs to tell me what a proxy is and under what
circumstances I would be using one.  Chances are good that
I would use this because I *need* to on the network I'm on.
It needs to tell me where I can find the information.  It
needs to tell me when I can use the autoconfiguration URL
(why wouldn't I want it to autoconfigure?) and where I can
find that URL.

That helps cases (1) and (3).  For case (2), you really
want a series of tutorials and troubleshooting pages to
help people get connected.  Since it seems likely that
people might land on this page when they're looking for
those tutorials, link to them.  Prominently.

When I first started working on Mallard and talking about
topic-oriented documentation, I believe the phrase I used
was "cross-linked up the wazoo".  I stand by that.  A lot
of users will be helped by long-winded tutorials.  And a
lot of users will be helped by quick references.  And the
nice thing is, we can totally have both.

--
Shaun