Re: About GNOME / return / duck related question

[karderio <karderio gmail com>]

Hi :o)

On Sun, 2006-12-17 at 11:11 +1300, Matthew Paul Thomas wrote:
> 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? ;-)

Of course they are.

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

Your comments about the documentation process would seem much more at
home in the Mallard discussion. Might I suggest you check it out :

http://live.gnome.org/ProjectMallard

Our current process is far from ideal, part of Mallard is to fix it, as
much technically as stylistically.

A side note : I stumbled upon a nice "helpy" word the other day :
"Eroteme", this is another name for a "question mark". I'm suggesting it
here, perhaps not to replace the "Mallard" name, if we've become fond of
it, but maybe for some sub-project.

Love, Karderio.