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 ...
    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.

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


CategoryDocumentationProject

Apps/Yelp/ConsistentDocs (last edited 2013-11-18 19:11:56 by WilliamJonMcCann)