RFC: TopicBasedHelp specification

Matthew Paul Thomas mpt at myrealbox.com
Sun Nov 12 06:57:53 UTC 2006

On Nov 10, 2006, at 8:09 PM, 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.

That's a false dichotomy -- it's possible to do both. However, as I've 
said previously on this list, I think lists of Frequently Asked 
Questions are a bad idea.

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

Then you are a rare and special person. :-) Most people will flee from 
anything that's called "documentation", let alone get involved in 
writing it voluntarily.

> I would argue we do a great disservice to our readers and community if 
> we provide only topic based help.

The TopicBasedHelp specification explicitly applies only to the 
information currently provided in the Desktop Guide and Server Guide. 
It does not apply to other things that are better as manuals, such as 
the Packaging Guide.

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

The proposed change is about the structure and organization of the 
help, not about its contents. There are many holes in the current 
contents (How do I connect to the Internet? Why have all my windows 
diappeared?), but they are mostly orthogonal to the structure and 

> Are we changing help to optimize for search instead of changing help 
> to make it better?

That's a false dichotomy. The former is an essential part of the 
latter, because a large majority of people *do* search rather than 

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

That's also a false dichotomy, and it's not about mimicking Microsoft. 
It's about making people more effective when using Ubuntu.

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

And for the same reason you bought a printed book instead of reading 
online guides to SQL, in-depth manuals for Ubuntu should be targeted at 
the print medium instead of being crammed into the help viewer.

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

There are plenty of relevant links in

Matthew Paul Thomas

More information about the ubuntu-doc mailing list