← 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 02:50 PM, Jason Cook wrote:
The reason it may be a problem is that often when I don't have an internet connection, I need to know how to use an applications that have not yet learned how to use or am experiencing problems with. Though most are self-explanatory, some app are more complex and, when using this method, I can't use them or solve the problem until I get and internet connection. As I previously mention, if there was an easy way to download the documentation for offline use, then this method would work. Until there is a way to access the internet from *everywhere* this, at least in my opinion, this won't work.

Your point is significant.

Let's differentiate between application help and Ubuntu Help. That is, many applications (gnome ones, for example) already deliver their help (and translations of it) on disk through packages. I don't see why this shouldn't continue (for some time anyway). Thus, your use case is addressed.

In the meanwhile, there could be a wonderful and fun Ubuntu help web portal that starts to pick up the job of non-app-specific help.

Cheers,
Kyle

On Fri, Jul 9, 2010 at 12:01 PM, Kyle Nitzsche <kyle.nitzsche@xxxxxxxxxxxxx <mailto:kyle.nitzsche@xxxxxxxxxxxxx>> wrote:

    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>
        <mailto:jwcampbell@xxxxxxxxx <mailto:jwcampbell@xxxxxxxxx>>>
        wrote:

           Hi All,

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

           _______________________________________________
           Mailing list: https://launchpad.net/~ubuntu-manual
        <https://launchpad.net/%7Eubuntu-manual>
        <https://launchpad.net/%7Eubuntu-manual>

           Post to     : ubuntu-manual@xxxxxxxxxxxxxxxxxxx
        <mailto:ubuntu-manual@xxxxxxxxxxxxxxxxxxx>
        <mailto:ubuntu-manual@xxxxxxxxxxxxxxxxxxx
        <mailto:ubuntu-manual@xxxxxxxxxxxxxxxxxxx>>

           Unsubscribe : https://launchpad.net/~ubuntu-manual
        <https://launchpad.net/%7Eubuntu-manual>
        <https://launchpad.net/%7Eubuntu-manual>

           More help   : https://help.launchpad.net/ListHelp







--
Jason Cook




References