← Back to team overview

ubuntu-manual team mailing list archive

Re: An interesting blog by Matt Zimmerman touches on docs


Hi Jason?
On 07/09/2010 06:32 AM, Jason Cook wrote:
I think that a cloud based solution is a great idea. But for mobile users this would a problem.
Why do you think a web/cloud-based help system a problem for mobile users?

One possible solution would be to include *all* of the content that is available online in a repository that *gets updated when the contents on the web changes*. Then is is not just static and can be redesigned. If the downloaded format was HTML, then this would not require another application. I think that a cloud based solution would be great, but there needs to be a easy way to download all of that content locally.

On Wed, Jul 7, 2010 at 8:30 PM, Jim Campbell <jwcampbell@xxxxxxxxx <mailto:jwcampbell@xxxxxxxxx>> wrote:

    Hi All,

    On Wed, Jul 7, 2010 at 6:34 PM, Shaun McCance <shaunm@xxxxxxxxx
    <mailto: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 forward.


    Mailing list: https://launchpad.net/~ubuntu-manual
    Post to     : ubuntu-manual@xxxxxxxxxxxxxxxxxxx
    Unsubscribe : https://launchpad.net/~ubuntu-manual
    More help   : https://help.launchpad.net/ListHelp

Follow ups