RFC: TopicBasedHelp specification

[Richard Johnson]

On Tuesday 14 November 2006 02:25, Matthew East wrote:
[snip]
> (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.)

Well, we are kind of use to just following along, but I was concerned when I 
couldn't find a project similar to Mallard for KDE/Kubuntu. I spoke to Phil, 
KDE doc guy, and he would like to see some sort of "Topic-Based Help System" 
as well with KDE. Maybe this could actually be good, because if we come up 
with something, we just might have the chance to offer it upstream, which is 
a win for Ubuntu/Kubuntu.

[snip]
> 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/

I like this idea, and as a matter of fact, the proposed layout[1] we have 
discussed within the Kubuntu side, is very similar actually. I think I kind 
of grabbed from that page, but as well as the layout of the Official Ubuntu 
Book. I know, we will discuss it here so everyone knows, and I apologize for 
not doing so earlier.

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

+1

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

Would this put each topic in its own page, or do we do it on a question/answer 
per page? Either way is a good idea, and I'm sure further discussions will 
iron this out.

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

I have been looking over a bunch of pages dedicated to topic-based help 
systems (MacOSX and Microsoft mostly), and it is a unanimously the most 
favorable form of help/documentation for software.

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

I don't think I could disagree with any of the points you made at all, and I 
have actually been sold on the idea for the past day or so after reading up 
on topic-based help. On the documentation side it isn't all that difficult, 
and from the pages I read, it seems they all still use DocBook to achieve the 
documentation. Microsoft starts off with a DocBook file and then converts it 
to their .chm stuff.

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

I am sure we will iron out the achievement stuff in no time, and I think there 
will be plenty of good ideas come of this now. Thanks Matt for taking the 
time and dedication on this one! No more "head>wall" ;)

-- 
.:Richard Johnson
.:nixternal at ubuntu.com
.:ubuntu.com .:kubuntu.com .:edubuntu.com .:xubuntu.com
.:http://nixternal.ubuntu-rocks.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20061114/ed763296/attachment.pgp>