Re: About GNOME / return / duck related question

[karderio <karderio gmail com>]

Hi :o)

On Mon, 2006-12-11 at 23:17 +1300, Matthew Paul Thomas wrote:
> On Dec 8, 2006, at 5:26 AM, karderio wrote:
> > ...
> > On Thu, 2006-12-07 at 01:34 +1300, Matthew Paul Thomas wrote:
> > ...
> >> If I was having trouble opening an Excel spreadsheet in Gnumeric, and 
> >> I didn't yet know that Gnumeric didn't offer any help on opening 
> >> Excel
> >> spreadsheets specifically, I would get a bit annoyed if I read through
> >> Gnumeric's "Opening a file" help, only to realize that it was
> >> word-for-word the same as the "Opening a file" section in almost every
> >> other application.
> >
> > I'm not sure exactly what would be annoying about seeing the same thing
> > twice...
> 
> It would waste time, it would make people less willing to seek further 
> help, and it would make them grumpy. All of these would make success 
> less likely.

Possibly, yes, I admit I hadn't given it much thought when I wrote that.

> > ...
> > As it strands, we must (should) explain the "open file" function for
> > every app.
> > ...
> 
> No, really, you shouldn't. :-) Help (on-screen help, that is, not 
> manuals) should concentrate on the things that people are likely to 
> want help with, because cluttering the help with other stuff makes the 
> helpful stuff harder to find. The helpful stuff should not include 
> something as simple as opening files, unless there is something badly 
> wrong with the filepicker (in which case, fix the filepicker instead!), 
> *or* there is something special about opening files in that particular 
> application (e.g. "my Excel spreadsheet isn't opening properly, what 
> can I do?").

I was referring to our current policy for writing documentation, which
is described as "comprehensive" in the style guide [1]. What we are
currently working to is to document every function of an app, regardless
of if it is documented elsewhere.

We currently have no distinction between manuals and online docs,
AFAICS.

The "(should)" above meant that if we did things properly we would
document each "open file" function, but we don't manage to do this
because of the lack of people who want to write docs ;)

> What would be cool is an "&operatingsystem; Basics" tutorial that 
> teaches people how to open files in general, along with other basic 
> tasks such as using the clipboard and manipulating windows. I think 
> that would be the only appropriate place for help on such topics.

Part of the Mallard project [2] is revising our documentation style. You
seem to have some good suggestions for bettering our process, perhaps
you would be interested in contributing to Mallard ?

Love, Karderio.


[1] "Describe all of the functionality of a product. Do not omit
functionality that you regard as irrelevant for the user."
http://developer.gnome.org/documents/style-guide/fundamentals.html

[2] Sorry, I can't provide the URL, as the wiki is down. If you search
for "Mallard" on live.gnome.org you should find it no problem.