← 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.


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>>>

           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:


        > 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
               help into applications. (It was Phil's idea, although
        he might
               not realize it.) Imagine help buttons and menus
               populated with the most relevant content, searching for
               directly in the help menu, and on-board help blurbs
        that come
               directly from the help and link into it for more

               These are the sorts of things that user assistance
               are dreaming about, but most help tool vendors are
        still stuck
               in the 90s. We have the opportunity to blaze new trails
               free software. Stop playing catchup and make UA
               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
               thinking about how to really improve things, we'll lock
               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
           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
           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
           help, but they don't concern themselves with fitting all of
           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

Jason Cook