Re: About GNOME / return / duck related question
- From: Matthew Paul Thomas <mpt myrealbox com>
- To: karderio gmail com
- Cc: GNOME Documentation <gnome-doc-list gnome org>
- Subject: Re: About GNOME / return / duck related question
- Date: Sun, 17 Dec 2006 11:11:47 +1300
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]