Observations in packaged Ubuntu Documentation (Hoary)

[Matthew Thomas]

Important stuff first: I would love to start work on the Ubuntu help, 
this week, if only I could work out how to do it. None of the help docs 
seem to be in the ubuntu-docs SVN repository (except for the Quick 
Guide), and I can't find them in the Web mirror of Gnome CVS either.

So can someone please tell me where to start? (And please don't tell me 
the front page is "auto-generated", I've been told that several times 
already, I want to know *how to change it*.)

Jerome Gotangco wrote:
>...
> 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.

People use help as a last resort, only if nearby humans fail them, and 
sometimes only if the Internet fails them too (as PageRank may produce 
better answers than the technical writers for a software vendor).
<http://www.g2meyer.com/usablehelp/lastreso.html>
<http://developer.apple.com/documentation/LegacyTechnologies/Conceptual/AquaHIGuidelines/AHIGHelp/chapter_14_section_2.html>

But yes, *if* we can build up a reputation for having useful help, 
people will prefer to use that rather than the wiki or other Web sites. 
Using a local help viewer is much quicker, more compact, and less 
cluttered than using a Web browser (those advantages apply equally to 
the help viewer interface and to the help pages themselves).

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

More likely, they won't make any such distinction. ("'Gnome'? What's 
this 'Gnome'? I thought I was using Ubuntu!")

I'm developing a hierarchy of topics for Ubuntu Help on the wiki
<https://www.ubuntulinux.org/wiki/LocalHelp>.

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

If a find toolbar (not to be confused with a search function) would be 
useful for any help page, that page is too long. And I have no 
particular love for gtkhtml, but if Gecko would be better than gtkhtml 
for any help page, that page is too complicated. 
<http://winwriters.com/articles/checklist/>

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

Agreed. So, how do we do it?

Thanks
-- 
Matthew Thomas
http://mpt.net.nz/