ubuntu-manual team mailing list archive
Mailing list archive
Re: An interesting blog by Matt Zimmerman touches on docs
On Wed, Jul 7, 2010 at 6:34 PM, Shaun McCance <shaunm@xxxxxxxxx> 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
> > browser.
> > 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.
> 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.
> 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.
To be fair, I don' t think that the two approaches to help have to be
mutually exclusive. What Shaun is talking about is awesome
application-level help. There will still be a need for people who want that
help content in different formats, whether they be manuals or help that is
searchable on the web.
As for on-disk vs. cloud/web-based content, I think having more web-based
content is necessary now. We would still have the option of keeping on-disk
help relatively light. For example, we could not include (as many?)
screenshots in on-disk help as would be available in other formats.
Also, as far as I know, Ubuntu is one of the few distros that ships a good
amount of on-disk help at all. Fedora just ships their release notes in the
main install, and OpenSUSE (I think) just features some sort of
getting-started guide. Both have their other help available for download on
their websites. Does anybody know how RHEL and SUSE have theirs set up? Do
they have much "distro-specific" help in the base install?
As for Apple and Microsoft, they may have a good amount of on-disk help, but
they don't concern themselves with fitting all of their OS and applications
onto a 700mb CDROM. For base installs they have DVD's and having some of
their content accessible via the web.
I bring up those comparisons not necessarily to say, "Oh, they do it that
way, so that way is the best way," or to say, "Just do it however X group /
company is doing it," but to set realistic expectations for us. I want us
to be mindful of bandwidth / offline-access issues like the ones that Phil
W. brought up, and want to give room for Shaun's application-level help
ideas, but a better web-presence for Ubuntu help would also be a big step