Re: About GNOME / return / duck related question

[Matthew Paul Thomas <mpt myrealbox com>]

On Dec 16, 2006, at 12:51 PM, karderio wrote:
> ...
> > > As it strands, we must (should) explain the "open file" function for
> > > every app.
> ...
> 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.
>
> 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 ;)

Do you think possibly those two things are related? ;-) Depth-first 
traversals of the user interface are not an exciting thing to write, or 
to read. And writing the eleventy-twoth version of "When you start 
&app;, the following window is displayed" can't be fun, either. 
Meanwhile, for example, Totem has no "What to do if a movie won't play" 
help page, Rhythmbox has no obvious "Sharing your music" help page, and 
Seahorse has no "What are keys used for?" help page -- all of which 
would be more interesting to write *and* more useful to read.

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

I highlighted some differences between books/guides and on-screen help 
on the Ubuntu documentation list earlier this year.
<http://article.gmane.org/gmane.linux.ubuntu.doc/6159>
Manuals fall much more into the "books/guides" category than the 
"on-screen help" category.

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

I don't know much about process, but I've researched help usability a 
fair bit, helped Don Scorgie design improvements to Yelp's search, and 
I know about designing markup languages. So maybe I can help with the 
specification for Mallard's file format.

Cheers
--
Matthew Paul Thomas
http://mpt.net.nz/