Observations in packaged Ubuntu Documentation (Hoary)

[Jerome Gotangco]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hello All,

After having some good debates on the documentation infrastructure, i
took the time to look into our existing packaged documents in hoary and
check what needs to be done to put order in what we currently have. I
have the firm belief that users would refer more to packaged
documentation that has a logical flow of info before checking out
external help pages like the wiki or other websites. Please note that my
observations are limited to what I know at the moment, I have yet to
familiarize myself on the technical aspects of the packaged
documentation but I have sworn to myself to focus on this much-neglected
aspect on ubuntu documentation.

Before going further, my definition of "packaged documentation" pertains
to two (obvious) components in hoary:

a. Ubuntu-specific docs - these docs are currently accessible in svn,
where most of our work is done. When packaged, ScrollKeeper registers
these docs so that they can be accessible to the help browser (yelp in
particular).

b. Gnome/other-specific docs - these docs were lifted from existing
documentation from upstream. Almost all of these docs are monitored by
the ScrollKeeper system that allows us to view the docs in yelp (in
Ubuntu) and khelpcenter (in Kubuntu).


Going back to packaged documentation, I have noted some user-centric (i
think) observations that I think we can improve on Breezy or
post-Breezy. While it would be nice to have these issues fixed in time
for Breezy, I won't be able to come up with an excuse if this does not
get fixed post-Breezy ;-)

1. When you open yelp (help), you are presented with the Gnome/Other
Help Topics. But notice that Ubuntu-related help topics are located
BELOW Gnome topics. New users would most likely want to refer to
Ubuntu-specific help pages first then go to Gnome/Other-specific help
topics later as they progress.

2. In an i18n/i10n system, notice that when you invoke System > About
Ubuntu, you are presented with the localized version of this document
(about-ubuntu-nn.xml [1]). But when you invoke System > yelp and select
"About Ubuntu," you are given the english version of the same document,
thus creating inconsistency in the Ubuntu-specific packaged docs[2].
This might not be the case of other installations though.

3. While almost all applications in Ubuntu have appropriate
documentation when invoked in their respective areas, the general help
page is quite difficult to navigate due to the limited features of yelp
at the moment, although plans for yelp 2.10 include a find toolbar and
switching to Gecko. Digging in through the help pages monitored by
scrollkepper can be confusing. We can get a head start if we start
fixing current packaged documentation.

How does existing wiki work fit in this spectrum? Frankly, we need to
cull (or probably make them optional) some upstream documentation, and
put in more relevant (and correct) wiki entries in our package as an
ubuntu-specific doc. What needs to be in or out is the question.

It would be nice if a developer with the knowledge on the underlying
technologies verify if the issues stated in this email is possible. I
will continue my research on this matter and would like to focus more on
this at the moment. There is so much information in the default install
of hoary (and most probably Breezy) that needs some housekeeping and
most importantly love :-)


Jerome


[1] Our Svn has this document with the following languages: Catalunya,
German, French, Italian, Portuguese, Tagalog, Xhosa.

[2] Not all documents in svn have translated versions of the languages
stated in [1].
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFCgYesuJQObal7aaARAq+DAJ9UXpdg5Q5bKj71CpVx91U3KjZ7UwCgvA/N
0GTM7G2wZPRlMCkncYfbptI=
=qRBW
-----END PGP SIGNATURE-----