Consistent Documentation
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.
The original email to gnome-doc-list can be read here: http://mail.gnome.org/archives/gnome-doc-list/2005-October/msg00012.html
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. (fixed in CVS)
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
One problem with scrollkeeper categories is that they don't match the groupings in the GNOME main menu. Eg, File Roller is under 'Accessories', but the docs are in Applications->System tools. Users will expect these to match up.
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 ...
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
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.
Progress
The table below specifies what cvs modules and applications have been looked at and fixed with regards to the issues mentioned above. Since some modules have not been ported to gnome-doc-utils yet, we should give them much lower priority.
In the future, please file a single patch against each cvs module, instead of each application. Thanks!
The applications listed below have been ported to gnome-doc-utils |
|||
CVS module |
application |
progress |
|
gnomemeeting |
gnomemeeting |
done |
|
gnome-applets |
accessx-status |
done 318968 |
|
gnome-applets |
battstat |
done 318946 |
|
gnome-applets |
charpick |
done 318950 |
|
gnome-applets |
cpufreq |
done 318949 |
|
gnome-applets |
drivemount |
done 318959 |
|
gnome-applets |
geyes |
done 318966 |
|
gnome-applets |
gswitchit |
done 318972 |
|
gnome-applets |
gtik |
done 318979 |
|
gnome-applets |
gweather |
done 318985 |
|
gnome-applets |
mini-commander |
done 318957 |
|
gnome-applets |
mixer |
done 318984 |
|
gnome-applets |
multiload |
done 318981 |
|
gnome-applets |
stickynotes |
done 318978 |
|
gnome-applets |
trashapplet |
done 318977 |
|
gnome-control-center |
control-center |
done 327784 |
|
gnome-desktop |
gnome-feedback |
pending 327785 |
|
gnome-keyring-manager |
gnome-keyring-manager |
pending 327946 |
Someone needs to write some docs |
gnome-netstatus |
gnome-netstatus |
done 318975 |
|
gnome-panel |
clock |
done |
|
gnome-panel |
fish |
done 318965 |
|
gnome-panel |
window-list |
done 318987 |
|
gnome-panel |
workspace-switcher |
done 318988 |
|
gnome-terminal |
gnome-terminal |
done |
|
gnome-utils |
gfloppy |
done |
|
gnome-utils |
gnome-dictionary |
done |
|
gnome-utils |
gsearchtool |
done |
|
gnome-utils |
logviewer |
done 327793 |
|
gucharmap |
gucharmap |
done 327792 |
|
gedit |
gedit |
done |
|
evince |
evince |
done 327791 |
|
epiphany |
epiphany |
done 327789 |
|
file-roller |
file-roller |
done 327786 |
|
gnome-system-tools |
boot |
done 327089 |
|
gnome-system-tools |
network |
done 327089 |
|
gnome-system-tools |
services |
done 327089 |
|
gnome-system-tools |
time |
done 327089 |
|
gnome-system-tools |
users |
done 327089 |
|
gdm2 |
gdm |
done 327796 |
|
sound-juicer |
sound-juicer |
todo |
|
zenity |
zenity |
done 318915 |
|
The applications listed below have not been ported to gnome-doc-utils yet |
||
CVS module |
application |
progress |
dasher |
dasher |
todo |
eog |
eog |
todo |
evolution |
evolution |
todo |
evolution-exchange |
evolution-exchange |
todo |
gcalctool |
gcalctool |
todo |
gconf-editor |
gconf-editor |
todo |
gnome-games |
klotski |
todo |
gnome-media |
gnome-cd |
todo |
gnome-media |
gst-mixer |
todo |
gnome-media |
gst-mixer |
todo |
gnome-media |
gstreamer-properties |
todo |
gnome-media |
grecord |
todo |
gnome-nettool |
gnome-nettool |
todo |
gnome-user-docs |
gnome2-user-guide |
todo |
gnome-user-docs |
gnome2-accessibility-guide |
todo |
gnome-user-docs |
gnome2-system-admin-guide |
todo |
gnome-user-docs |
gnome2-user-guide |
todo |
gok |
gok |
todo |
gnopernicus |
gnopernicus |
todo |
procman |
procman |
todo |
totem |
totem |
todo |
xchat-gnome |
xchat-gnome |
todo 344482 |
The applications listed below have no documentation |
||
CVS module |
application |
progress |
gnome-utils |
gnome-screenshot |
todo |
gnome-media |
vu-meter |
todo |
