RFC: TopicBasedHelp specification

Sat Nov 11 04:49:11 UTC 2006

On Friday 10 November 2006 22:09, Jonathan Jesse wrote:
> At the end of the day, Rich and I were talking over IRC and to be honest I
> don't think topic based help is the best idea.  We stop documenting the
> operating system and the programs instead switch to a Frequently Asked
> Question form of documentation.  Over the last two years I have learned
> more about Linux then I think I ever would be reading the documentation and
> then writing it.

I hate to say this Jonathan, but I am slowly changing my mind. Why? I have 
read over IEEE documentation standards (which did a horrible job at 
explaining anything), and I read over the differences between MaxOSX and 
Windows help systems. I think a "Help System" like this would be great, 
however I don't think it would/should replace our current documentation. 
Topic Based Help is just that, help, it isn't there to document every step, 
but provide quick and easy pointers to common problems. Now, within those 
problems, they do link to each applications manual or handbook. I have read 
over all of the topical, procedural, and conceptual based help systems, and 
every single one states that you should start with a manual.

So, if this help system which is currently spec'd isn't replacing current 
documentation, then it is a great idea. But if we are looking at creating a 
topical based help system to replace documentation, then this isn't such a 
good idea (my opinion of course). If I want to know a quick answer, boom I 
should have access on it, either by going directly to the topic, or by 
searching for it, which searching for it is better than listing by topic. 
However, now that I know my quick little fix, I might want to know more about 
the application. The topic based help system can't and won't do this, 
otherwise it is far more than a topic based help system, and now gets into 
the conceptual and procedural based systems, which are all interlinked one 
way or the other to a manual.

This has made me do a lot of reading tonight, and I learned some cool tricks 
as well when it comes to documentation type stuff. I actually learned that 
Microsoft documentation is w/o a doubt the best there is. Their help system 
is very cluttered, but there isn't much they don't answer. Why is this? 
Simple, all of their help is done with docbook, then converted to html and 
then linked and interlinked and linked some more.

> I would argue we do a great disservice to our readers and community if we
> provide only topic based help.  I spent some time looking through the KDE
> documentation today and all of the programs that have great documentation
> explain both the program and how to use.  The topic is "How do I use X
> correctly and solve the problem I have"

I agree with you here definitely, as we can't divert from the foundation that 
the Ubuntu Project is built on, and that is the current documentation types, 
i.e., Desktop Guides, Server Guides, About and Release Notes. If we continue 
doing this the same way we always have, and just include the topic based help 
system seperately, then lets rock and roll, but I don't think replacing all 
documentation is the answer, or making all documentation topic based 
questions.

> Are we changing help to optimize for search instead of changing help to
> make it better?  Are we trying to mimic MS and provide a great Knowledge
> Base along the lines of MSDN/Technet or are we trying to document how
> things work?  An example of this is that because of my job I now spend a
> lot of time in SQL something I don't know very well, if at all.  I can
> search the internet for different queries I can copy, I can search on
> MSDN/Technet to find the solution, or I can purchase a book for $60 and get
> a good grasp on the part of SQL I'm struggeling with (of course w/ work
> expensing it :) ). I feel it's the same way w/ Linux/(K)(Ed)(X)Ubuntu.  I
> can spend a lot of time searching on the forums and wiki, but if I want to
> understand how Krita works I turn to the documentation and read a greater
> in-depth handbook.

A Microsoft style help system is w/o a doubt the best there currently is. They 
do their documentation the same way we do with docbook, xsl, and html however 
they also convert to their funky .chm? help files as well. The help you see 
right up front is all topic based, but it is backed by extensive 
documentation on each application Microsoft produces.

> I guess I'm just not seeing the reasoning behind the switch and because of
> that would be the wrong to try and persuade someone to switch to something
> I don't believe in, or even understand.  I would love to learn more, should
> I look for topics or a handbook :)

I am still a little confused, because I have gotten a couple different sides 
to the story myself tonight. The idea is great, I am just not sold 100% on it 
due to my lack of knowledge on what exactly it is you are trying to reach 
with this system. I don't know if we are to remove our current documentation 
standards and replace them with this one, which refers to the Mallard 
Project, from what I see has been an idea for a couple of years, but no work 
as of yet. From what I read in the spec, we change our current documentation 
to be a series of questions and answers to what? Almost sounds FAQ'ish to me 
in a way.

I am sorry for my ignorance in this topic, but I am not understanding it 100% 
I don't think. I like it, but I don't like it ;)  If that ever made sense to 
you. More information, and better explanations would be needed. The Mallard 
Project documentation is sadly inefficient, however the link to an old doc 
spec had some great links to outside information. Most were broken, but 
detailed searching landed some good information.

Meeting time maybe on this one?

-- 
.: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/20061110/5dfde8bf/attachment.pgp>