Re: About GNOME / return / duck related question



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/




[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]