Worthwhile critique from Matthew Thomas

[Jerome Gotangco]

I went to Matthew's site once again and re-read the section on the help system.

I was driving to the grocer and was thinking about better ways to
present a help system that is useful to a user who dives into Ubuntu,
so I had to think myself as someone who came from another operating
system, say like Windows or MacOSX.

I also checked the forums as well as monitoring the #ubuntu chatroom.
After some observations on the user questions and conversations, my
assumptions are the following:

1. The user knows how to do things in his current operating system.
Either he has the software installed when he bought the machine or he
bought this particular piece of software to do something (say play a
DVD).

2. The user has knowledge of what Linux is, has tried some distros,
probably the most common 3 (RH/Fedora, MDK & SuSE), but didn't last
long because he couldn't do things that was used to in his current
system.

3. The user has enough experience to try out a new system for use at
home or probably work and is trying to research on the viability of
the new platform (Ubuntu) for daily use.

4. The user is experienced in handling a Linux system as a desktop, server, etc.

Therefore, I can think of a flow of documentation with this line of
thought. This may have been done by other distros like Linspire or
Lycoris, but I cannot say because I have not used them personally.

A. Welcome Note

B. About Ubuntu
 B.1 History...
 B.2 Manifesto....
 B.3 Joining...etc..

C. Running Ubuntu
 C.1 I want to do...etc...
   C.1.1 Play DVD
   C.1.2 Connect to the Internet...etc.

D. Maintaining your Ubuntu system
 D.1 Your Home Folder...
 D.2  Folder structure (what is this, where this goes, what it means,
etc.)...etc.

E. Going Further
 E.1 Learn Linux guide....(note: I've seen this on svn, this is the
learn linux stuff from a za website)
 E. Running Ubuntu as a server...etc.

F. Credits

G. Index

H. GNU/Linux stuff, licenses, etc...

This is a rough thought, looks like a book, but at least you have a
flow of thought that can be relevant to a new user, regardless of
experience level. I haven't even thought on how to present this in a
UI.

But then, we also consider the fact that yelp does not have a search
function. So that means, given the volume of possible documentation
that we may have (not to consider i18n), we need a help system that
has at least index and search.

I remember someone in #ubuntu saying that there is a need to
restructure our current documentation "in a logical flow from docbook
to wiki". My interpretation of this is that we build our documentation
as we have always done (with some new stuff included), but since these
docs are frozen along with release, any user who installs a few months
after release will have, technically, "old" documentation. That's
where the wiki comes in, some sort of "addendum" or "last minute
docs", like those loose sheets we have when we buy software or a
computer. However, these wiki entries should be controlled so that the
information is official and always changed as needed.

This thing may have been discussed before in previous chats or emails
before I became active in the DocTeam so feel free to remind me of
such.

jerome

-- 
Jerome S. Gotangco
GPG: A97B69A0 @ pgp.mit.edu
IRC: jsgotangco @ freenode #ubuntu, #ubuntu-doc, #ubuntu-devel, #ubuntu-ph