← Back to team overview

ubuntu-manual team mailing list archive

Re: An interesting blog by Matt Zimmerman touches on docs


Hello Shaun and all.

On 07/07/2010 07:34 PM, Shaun McCance wrote:
On Wed, 2010-07-07 at 17:13 -0400, Kyle Nitzsche wrote:

With which I agree in general.
* on-disk docs might effectively be limited to only what is necessary to
get started and get connected to the web (localized, of course).
* run-time help links might instead display appropriate content in the

Naturally, there are disadvantages, such as:
* no internet connection = no help (beyond the minimal on-disk help)
* umm.. any other disadvantages?
A greater disconnect between applications and their help. Our
traditional help consists of islands of documents that are
largely separate from the applications they document.
I don't quite understand this " greater disconnect". From the user's point of view (with an internet connection), I would expect that when they click the "Help" button, they don't care (and may not even know) if the content is served from the web or from the disk. In both cases, it displays in a separate application (browser vs. yelp). Indeed, since the web content is (I argue) more nimble, more able to be current, with more up-to-date translations, and includes (clearly labeled) user commentary/articles/forums/corrections, it is more likely to be (overall) correct and helpful, which means the connection is stronger, rather than weaker.
One of my current projects is a library for deeply integrating
help into applications. (It was Phil's idea, although he might
not realize it.) Imagine help buttons and menus automatically
populated with the most relevant content, searching for help
directly in the help menu, and on-board help blurbs that come
directly from the help and link into it for more information.

I think context-sensitive help (minimal) is important in some cases. However, I don't see exactly why the content has to be on-disk. One can imaging that one clicks a help widget in an application, it opens a URL that has encoded in it: the user's locale, the OS, application, the application version, the currently displayed UI. These could be used on the server side to display context sensitive help.

Searching help is critical and currently underpowered. Again, I don't understand the requirement that this be performed on disk, given this ^^^ sort of idea.

These are the sorts of things that user assistance professionals
are dreaming about, but most help tool vendors are still stuck
in the 90s. We have the opportunity to blaze new trails with
free software. Stop playing catchup and make UA professionals'
mouths water.

It's possible to have this sort of deep integration with cloud
content, but it's harder. I have no doubt that help will move
more and more to the web, but then, applications will move more
and more to the web as well. If we jump there too early without
thinking about how to really improve things, we'll lock ourselves
into an outdated and inadequate help model.

The following everyday apps from my lucid system (at least) have (only) web-based help:

 * Thunderbird
 * Firefox
 * Chromium-Browser
 * Google Docs

The lack of on-disk help for these does not seem to be impeding their paths through life. I would argue it *facilitates* their growth.

Overall, I am talking about a deep shift, and yes, we may consider it a "cloudy" shift.

Consider the transition of user expectations regarding "help". I assert that they now look to the web *first* for answers, and that this trend will only increase. They have come to feel, correctly, that they are more likely to get their actual problem answered quickly from the web than from Help. Why? Because experience has taught them that official help content is never complete, never up-to-date, never organized well enough to enable one to rapidly find the answer they need. (Well, 'never' may be an overstatement, but you get the point.)

Embracing this idea means a conceptual transition on the part of those who produce help systems. * They don't write it all, realizing they can't do it, practically speaking
 * They write 'just enough'
* They facilitate (through well-designed web portals) user commentary, user submissions, corrections, etc. * They empower "editors" to review user submissions and move them out of the fray and into prominence
 * They facilitate translation

It becomes primarily a role of setting things up, writing some required content, and facilitating the rest.



Follow ups