[Ubuntu-manual] An interesting blog by Matt Zimmerman touches on docs

[Jason Cook]

The inclusion of on-disk documentation should be up to the user and be
"package-wide". Having a "documentation" package that has the documentation
for all installed applications. The way this would work (at least in theory)
is:

   - on instalation of this package
      - finds all installed packages
      - check for documentation
      - download documentation
   - on installation of new package(s)
      - find newly installed packages
      - download new documentation
   - on removal of package
      - remove install documentation

Being done this way allows the user to choose weather documentation is
installed by default and conserves disk space by only having the
documentation for installed application.This would also eliminate the need
to install a separate package (such as openshot-docs) for documentation, it
would be added automatically.

I agree that web-based apps don't need on-disk help. Non-web-based should
have web and local (as per above) documentation. As Kyle mentioned, Ubuntu
Help should only basic getting started documentation should be included. I
would also argue that this should have shortcuts on the desktop (on both the
live CD and for all new accounts) to make it easier to find.

On Fri, Jul 9, 2010 at 3:54 PM, Kyle Nitzsche
<kyle.nitzsche at canonical.com>wrote:

> Hi Jim,
>
> On 07/09/2010 03:38 PM, Jim Campbell wrote:
>
>
>>
>> On Fri, Jul 9, 2010 at 1:50 PM, Jason Cook <jason at cookcrew.ca <mailto:
>> jason at cookcrew.ca>> 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.
>
> Cheers,
> Kyle
>
>> Jim
>>
>
>
>


-- 
Jason Cook
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20100709/229f698f/attachment.html>