RFC: TopicBasedHelp specification

[Jonathan Jesse]

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

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

-----Original Message-----
From: ubuntu-doc-bounces at lists.ubuntu.com
[mailto:ubuntu-doc-bounces at lists.ubuntu.com] On Behalf Of Andreas Lloyd
Sent: Friday, November 10, 2006 6:42 PM
To: nixternal at ubuntu.com
Cc: ubuntu-doc at lists.ubuntu.com
Subject: Re: RFC: TopicBasedHelp specification

Richard Johnson wrote:
> On Friday 10 November 2006 14:53, Jonathan Jesse wrote:
>   
>>> Then please do whatever you can to get KDE using a topic-based help
>>> system sometime in the next six months as well. It's a better approach
>>> regardless of the environment you're using.
>>>       
>> Wow what a comment.  Please turn the ship of KDE documentation.  How do
>> you think they will react to this suggestion by someone who doesn't
>> contribute any documentation upstream (yet)?  This is not a very serious
>> approach to take.

Basically, what MPT says is: Get in touch with the KDE doc team and hear
about the possibilities for topic-based help. As it is with the GNOME
upstream, nothing is decided yet, since MPT has yet to get in touch with
them about it, and they haven't made apparent progress for a while.

Nothing is settled yet. This spec is just meant to show the general
lines along which we would like to move the Ubuntu documentation for the
Feisty release. We can keep the documentation in DocBook for now and
work towards editing the desktop guides into topic-based pages as the
spec suggest, and if the GNOME upstream brings something usable to the
table, we can adopt that.

So the focus of this discussion should be: Topic-based help: How should
we do it? Do you have comments to the suggestions laid out in the
specification? Are there concerns in making the Desktop guides
topic-based that we have overseen - especially in relation to
K|Ed|Xubuntu documentation - and how can we address them?

Cheers,

Andreas


-- 
https://launchpad.net/people/lloydinho


-- 
ubuntu-doc mailing list
ubuntu-doc at lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc