An interesting blog by Matt Zimmerman touches on docs

[Jim Campbell]

Hi All,

On Wed, Jul 7, 2010 at 6:34 PM, Shaun McCance <shaunm at gnome.org> wrote:

> On Wed, 2010-07-07 at 17:13 -0400, Kyle Nitzsche wrote:
> >
> http://mdzlog.alcor.net/2010/07/06/weve-packaged-all-of-the-free-software-what-now/
>
> [snip]
>
> > 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.
>
> [snip]
>
> > 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.
>
> --
> Shaun
>
>
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
forward.

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20100707/8d4ac055/attachment.html>