So, I've embarked on a mission to tidy up how some of our documentation is listed in yelp. My main goal here is consistency.
A wikified version of this email can be found at http://live.gnome.org/Yelp/ConsistentDocs
My first goal is to: 1) Verify that each help document is in a reasonable category Yelp uses scrollkeeper categories to create the table of contents which you see when yelp first opens. Some modules in GNOME obviously are in incorrect or unreasonable categories. One such example is Zenity. The zenity/help/zenity.omf.in file lists its category as "GNOME|Desktop" where a more appropriate category would be "GNOME|Utilities". Because it is currently set as "GNOME|Desktop" it shows up along with the Accessibility Guide, the User Guide, etc in the table of contents. These obviously should not be categorized with Zenity. By changing this to "GNOME|Utilities", zenity will appear in the Accessories -> Applications in the table of contents, which is much more reasonable given the nature of the application. (To see how scrollkeeper categories are converted into the table of contents in yelp, see the yelp/data/scrollkeeper.xml file) I've created a tracker bug against yelp (for lack of a better component) here: http://bugs.gnome.org/show_bug.cgi?id=318900 * I would ask that you would file other bugs as you see fit, and add them as a dependency to this bug. If you are unsure about a category, please email gnome-doc-list so we can discuss the most appropriate category. Current scrollkeeper categories can be found here: http://scrollkeeper.sourceforge.net/documentation/categories.html My second goal is to: 2) Standardize the titles of each document by removing version numbers, fixing capitalization, removing unnecessary articles and adding a type to the title such as "Manual", "Tutorial", or "Guide". - Many documents have a trailing version number in their title. I would like to remove this from all documents, since docbook provides an element, <releaseinfo>, to contain this. Having the version number in the title is superfluous and distracting. This will need to be changed in translations as well. - As for capitalization, refer to the HIG guidelines at: http://developer.gnome.org/projects/gup/hig/2.0/design-text-labels.html#layout-capitalization Basically, capitalize all words in the element, with the following _exceptions_: * Articles: a, an, the. * Conjunctions: and, but, for, not, so, yet ... * Prepositions of three or fewer letters: at, for, by, in, to ... - Unnecessary articles include "The", "A", "My", etc. Please do no use these in the document title. One such example is " The Aisleriot Manual" which should simply be "Aisleriot Manual". - Finally, your documentation should indicate the type of document in the title. * "Manual" - If the document describes usage information for an application, then include "Manual" at the end of the title. Please don't use "Help Manual" or "Reference Manual". * "Guide" - If the document is user-centric and describes how to perform tasks related to a specific topic, then include "Guide" at the end of the title. Examples, "Accessibility Guide", "System Administration Guide". * "Tutorial" - self explanatory I've created a tracker bug against yelp (for lack of a better component) here: http://bugs.gnome.org/show_bug.cgi?id=318887 There is already one dependency for that bug which fixes all the above issues mentioned with a patch, except for the translated docs. * I would ask that you would file other bugs as you see fit, and add them as a dependency to this bug. If you are unsure about something please send a message to this list. One last remark: it would be nice if all documents included a meaningful <abstract role="description"> element in the articleinfo or bookinfo sections of the docbook file. This text will be added below the entry in the table of contents that yelp displays. "User Manual for &appname;" is _not_ a meaningful description. -- Brent Smith <[EMAIL PROTECTED]> IRC: smitten _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
