← Back to team overview

ubuntu-manual team mailing list archive

Re: An interesting blog by Matt Zimmerman touches on docs


Hi Jim,

On 07/09/2010 03:38 PM, Jim Campbell wrote:

On Fri, Jul 9, 2010 at 1:50 PM, Jason Cook <jason@xxxxxxxxxxx <mailto:jason@xxxxxxxxxxx>> 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.

There seems to be some concern that Ubuntu would not ship any non-web-based desktop help. I want to stress that this would not be the case. Moreover, keep in mind that much of the help that is on the system comes from upstream application developers. So, if I work on the gedit docs, and the gedit docs get shipped with gedit . . . You would have gedit docs on disk.

Now, I might see some issues with a gradual drift of application developers of putting more of their help online rather than including it on-disk. That is up to the application developers (e.g., the shotwell documentation is all on the shotwell website). It's also up to KDE and Gnome to drive those kinds of decisions at the application level.

Consider the needs of a server administrator, though. The server docs are not easily viewable on a server, and the server docs aren't in a format that is easily searchable on the web. Having a well-updated support website could make things easier for that person. Also, consider a scenario where an Ubuntu upgrade causes a problem on certain computers. Right now people hear about fixes through blogs and forum posts, but perhaps an update could be quickly put up on the support website to let people know how to fix the problem, and people could be directed there.

Or let's say that you get an error in your application, and you search for it on the support center website. Perhaps the site could say, "We didn't find anything on that error - would you like to file a bug report?"

I do think we'll have to work out how to make sure that user help for Ubuntu-specific apps like the Software Center is available both locally and on the web, (though I'm not sure how well the Software Center functions without web access . . . ), but those kinds of things can be done.

Along these lines, I think we can perhaps usefully divide help into categories: * application that are fundamentally web-based (for example, Software Center, browsers, Ubuntu One, email). It seems perfectly reasonable for these to offer their help only on the web, and many do just that. * applications that are not fundamentally web-based (many examples). For these, web-based only help is a harder sell up front, but still, I think, the trend is towards hosting help online for them too (for reasons I described in my previous post). * Ubuntu help. This is 'everything else'. In this area, I argue for limiting on-disk content to Getting Started/Getting Connected and hosting the rest in a wonderful, community oriented and community-engaging web site.

Note also that hosting content primarily on the web may simplify the content pool source format problem by eliminating some required delivery formats. And as such, the common pool could grow and be more widely used, potentially eliminating content (and translations of it) that may now be duplicated in different Ubuntu variant help systems.


Follow ups