Ubuntu Help: what it should/shouldn't include

[Phil Bull]

Hi Matthew,

While I think that you have some valid points, and while I respect your
opinion, I think that you have made a lot of assumptions which need to
be justified.

On Tue, 2007-08-07 at 00:05 +1200, Matthew Paul Thomas wrote:
[...]
> I think there are two important principles here.
> 1.  Help should be where people expect to find it.
> 2.  Ubuntu Help is a help system, not a software directory or
>      encyclopedia.

I agree with point one. But as for point two, what do you think a help
system should be? Surely an encyclopaedia can be used as a type of help
system in certain circumstances?

> For example, apply these principles to the Liferea newsreader.
> 1.  Liferea has a Help menu. Therefore, people will expect Liferea help
>      to be accessed from that Help menu. If Liferea help is put in
>      ubuntu-docs instead, most people who need that help *will not find
>      it*.

Can you justify these statements? While it seems logical to us that a
user would go to the application's help menu for help, do users really
follow this pattern of behaviour? My personal experience is that they
don't; most of them just use Google.

> 2.  Liferea, like dozens of other feed readers, is not installed by
>      default. Therefore, just as with those dozens of other feed readers,
>      instructions on using Liferea should not be shipped by default.

As far as I'm concerned, we're answering the question 'How can I read my
news feeds?', and a possible answer involves installing Liferea and
adding a feed. The reason that this particular answer was chosen was a
judgement call - other applications would be just as valid.

> *   "Program X's help is online, therefore people offline won't see it,
>      so we should include extra help in ubuntu-docs."

Another issue which I didn't articulate at the time was that of
translations. If we include help in ubuntu-doc, it gets translated.
While upstream should _really_ provide useful docs in a translatable
format, they don't always. We could do things 'properly' and *possibly*
get useful, translated help in upstream in 12 months, or we could work
around these issues by adding to ubuntu-docs.

I have been choosing the latter option because it help users now, and
because it's easier and cheaper in terms of time. In the long term, I
agree this isn't sustainable. But we may as well have a workaround in
place until we can do the right thing, don't you agree?

>      But "supplemental" doesn't work for help pages, unless they are
>      directly linked to each other.

I agree with this. This is something we need to work on, if possible,
but remember that we can't always link to other help easily due to the
use of incompatible help systems.

> *   [...] it's still worth contributing upstream even
>      if that's 20 times harder than contributing to ubuntu-docs.

But will I, as a volunteer, still want to contribute if its 20 times
harder? What if I don't agree with their documentation license, or would
need to learn a new documentation system? Do I have enough free time?
Will they listen to my suggestions, or review/accept my patches?

> I am not suggesting Ubuntu Help should become much smaller than it
> is. 
> Rather, I think it should concentrate on covering topics that don't 
> belong elsewhere.

Your list of questions seems sensible. However, what makes these
questions different from 'How can I read news feeds'? If we document
"How do I rearrange the menu?", we're duplicating material in the GNOME
Desktop User Guide. If we document "All my windows have gone!", we're
writing material which probably belongs in the DUG too.

Thanks,

Phil

-- 
Phil Bull
http://www.launchpad.net/people/philbull