RFC: TopicBasedHelp specification

[Matthew East]

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

Hi,

* Richard Johnson:
> On Sunday 12 November 2006 00:57, Matthew Paul Thomas wrote:
> [snip]
>> I don't see any conflict there. There are three basic kinds of topic:
>> *   How do I do X?
>> *   I have problem Y, how do I fix it?
>> *   What is Z and how does it work?
> 
> How do we choose the questions that will get answered. This does sound 
> strangely like an FAQ, and after reading about Topic-Based help, the main 
> goal is to answer every questions, which extends it past the scope of an FAQ. 
> How do we choose those questions? hopefully not the most frequently asked 
> questions :)

This is getting really confused. Let's try and drag things back on
track. Note, I'm going to try to reply to a lot of the comments that
have been made, I've just taken Rich's as a starting point. Please note
that this is my interpretation of the spec, it probably doesn't
represent the author's intentions, but let's see if we can find some
middle ground and start working with this.

First of all, big letters. THIS SPEC IS NOT ABOUT FREQUENTLY ASKED
QUESTIONS. Those questions that MPT outlined above are simply different
types of documentation, as I understand the spec, he doesn't envisage
converting all of our documentation into questions and answers. The spec
 does not actually involve rewriting or replacement of our material. See
below for what I think this spec is actually about.

Secondly, big letters again. THIS SPEC IS NOT A THREAT TO KUBUNTU
DOCUMENTATION. For two reasons. First of all, the improvements that the
spec mentions are equally applicable to the Ubuntu and Kubuntu
documentation, which broadly speaking have the same layout.

(Having said that: the reaction from the Kubuntu guys is pretty natural,
considering the fact that the spec has been drafted from the point of
view of Gnome, mentions Project Mallard throughout, and doesn't mention
Kubuntu. I'd like to see that change.)

Thirdly, last time for big letters. THIS SPEC IS NOT ABOUT PROJECT
MALLARD. When and if Project Mallard ever gets implemented, we can
discuss the challenges it will raise for our multi-distro emphasis at
that time. With a bit of luck, the improvements in upstream will take
hold of Gnome and KDE at the same time. While on that subject, in
passing, see:
http://mail.gnome.org/archives/gnome-doc-devel-list/2006-October/msg00001.html.
Until then, no problem.

So with the caps out the way, what is the spec about? As I understand
it, it is simply about presentation. It's about turning a boring and
unhelpful list of guides into a more substantial topic based list from
which the user can immediately see where to go. Compare the current yelp
front screen (or the khelpcenter screen under the "Kubuntu Documents"
section), with this page: https://help.ubuntu.com/community/

The difference is that the latter is much more attractive because the
user can immediately see where (s)he is going and where the right
answers are. We can present the system documentation in a similar way to
the structure that it is presented on the wiki.

It's also about making the material more readable. At the moment we have
a lot of pages with long and unwieldy material. Splitting that up into
smaller pages (this is easily achievable by some sensible tweaks to the
xslt and the material itself) will make it more readable.

I think that those two things are clearly desirable. And I am also
pretty confident they are based on a thorough review of the theory
behind help which I know MPT has studied.

The spec clearly needs some work. If the team agrees with some of the
aims I've described above, then we can work on the spec to make it clear
that it is not about those things with the caps. It's obviously unclear
in its current state because it has caused a lot of confusion among people.

The spec also needs work because it doesn't, at the moment, contain any
description of how to achieve its aims.

But let's keep discussing it, and I think something fruitful will come out.

Matt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFWX14tSaF0w5rBv8RAqNsAJ4wqRxO8p8Kgd1RrD+jNdW2AhLxqgCdGw1o
KfWOvKsxvGx/3MlfnNZ9RNc=
=4wse
-----END PGP SIGNATURE-----