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. _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
