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