← Back to team overview

ubuntu-manual team mailing list archive

Re: An interesting blog by Matt Zimmerman touches on docs


What Kyle has just listed below sums up the intentions of the Ubuntu Support
and Learning Center perfectly - so perfectly, in fact, that I might just
copy and paste his words onto the wiki page for it!

This is the direction the manual team is heading in, no doubt about it.

On Tue, Jul 13, 2010 at 2:18 AM, Kyle Nitzsche

> My two-cent perspective on this topic (again ;-):
>  * In my opinion the overall trend is towards web-hosted help, for many
> reasons (of which I listed some at the start of this thread, but they
> include: easier for users to find content, easier for users to submit
> content, higher quality content through easy user feedback/correction, more
> flexible and dynamic content, broader scope of content (*ubuntu, for
> example), no need for building/packaging/installing, a more dynamic UI with
> beautiful design, with fresh eye-candy and a wonderful user experience,
> easier to have a common source pool, a wonderful web presence that is good
> *buntu 'marketing', etc.)
>  * As a first draft, I imagine something like this:
>  - *buntu help web portal
>  - with excellent search of all content, very prominent (and with ability
> to search various sub-scopes of the whole site, for example 'official
> Ubuntu' content, 'official Kubuntu' content, or 'user-submitted Ubuntu
> Light' content)
>  - official articles
>  - user-submitted articles (some simple source format, TBD)
>  - user-ratings of articles and comments on articles
>  - editorial team to identify and write core 'official' articles (source
> format, TBD, but needs to support at least xhtml and PDF, localized)
>  - editorial team also reviews user articles with high ratings and promotes
> to 'official'
>  - all main variants and their launchers covered (Kubuntu, Ubuntu/Gnome,
> UNE, Ubuntu Light, etc.)
>  - localization/translations facilities designed in from start
>  - site team to develop/maintain site
>  - build team to manage docs format, conversions, etc.
>  * There are disadvantages, for example no internet or very slow internet
> limits access to help. Although I presume the no internet/very slow internet
> situation will continue to become a smaller use case and may eventually all
> but disappear.
>  * Therefore, I propose the strategic direction for *buntu help should be
> towards a web-hosted help portal and away from packaged, on-disk docs.
> Naturally, it would need to be phased in, and the question is legitimately
> raised: how would users get critical content in the  meanwhile without web
> access, that is, could they download it, and if so how. I imagine that
> current docs will continue on their current track(s) for some time, during
> which time they would continue to be packaged and installable. During this
> time the *ubuntu help website could come into existence and may come to
> carry an increasingly important part of the load. If it succeeds, the need
> for comprehensive on-disk help would be understood to decrease and could
> therefore diminish in scope.
> As to "downloading" the web site help. Perhaps the only parts that would
> need to be downloaded would be the 'official' articles/content. So that
> could be made available as PDFs. It would be a simple matter to generate
> such PDFs when the articles are made official and to make them easily
> downloadable.
> Let me state one obvious point: all of this is highly theoretical and
> speculative. It is not clear whether the ubuntu-docs and ubuntu-manual
> communities see this as the correct direction.
> Cheers,
> Kyle
> On 07/10/2010 08:22 AM, Jason Cook wrote:
>> I think that limiting the documentation is a good idea. I think there if
>> the documentation is removed from the CD then there needs to be an easy way
>> to download it. The php.net <http://php.net> is one way to do it.
>> On Sat, Jul 10, 2010 at 12:55 AM, Phillip Whiteside <phillw@xxxxxxxxxx<mailto:
>> phillw@xxxxxxxxxx>> wrote:
>>    Hi Jason,
>>    I'm sort of aware that wget can 'suck' in web sites (e.g. wiki
>>    pages). I have not used it, but it does seem up to the job.
>>    http://ubuntuforums.org/showthread.php?t=153766
>>    and
>>    http://ubuntuforums.org/showthread.php?t=321434
>>    I do appreciate that room is tight on a CD, but if the images are
>>    kept to a minimum, html code as generated is quite a low over head.
>>    i'm not too sure how hard it would it would be to provide
>>    something like http://php.net/download-docs.php
>>    As we are discussing documents, as well as on / off line help is
>>    this a path worth investigating?
>>    I've seen a couple of instances of chm documents and have the
>>    linux version of the reader, it works very well. I'm not saying
>>    that we should go down that route, just that it is possible to get
>>    the html version of a help area down-loaded.
>>    Regards,
>>    Phill.
>>    On Sat, Jul 10, 2010 at 12:58 AM, Jason Cook <jason@xxxxxxxxxxx
>>    <mailto:jason@xxxxxxxxxxx>> wrote:
>>        I defiantly agree that the /primary/ development should be
>>        done on the web based content, *but* there should be a way to
>>        have the docs available offline. The way I recommended would
>>        work well, but would be *very* difficult.
>>        On Fri, Jul 9, 2010 at 4:30 PM, Kyle Nitzsche
>>        <kyle.nitzsche@xxxxxxxxxxxxx
>>        <mailto:kyle.nitzsche@xxxxxxxxxxxxx>> wrote:
>>            Hi Jason,
>>            On 07/09/2010 04:08 PM, Jason Cook wrote:
>>                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
>>                         o finds all installed packages
>>                         o check for documentation
>>                         o download documentation
>>                   * on installation of new package(s)
>>                         o find newly installed packages
>>                         o download new documentation
>>                   * on removal of package
>>                         o 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.
>>            That's a reasonable amount of infrastructure development
>>            in order to support downloadable, translated docs with the
>>            primary goal of supporting the use case of a user who is
>>            not connected to the internet. Yet, it assumes they do
>>            have an internet connection at other times (in order to
>>            download the docs). While it is possible, I tend to think
>>            a more strategic direction is increasingly more web based
>>            help with increasingly less on-disk help.
>>            Cheers,
>>            Kyle
>>                Jason Cook
>>        --         Jason Cook
>>        --
>>        ubuntu-doc mailing list
>>        ubuntu-doc@xxxxxxxxxxxxxxxx <mailto:ubuntu-doc@xxxxxxxxxxxxxxxx>
>>        https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>> --
>> Jason Cook
> _______________________________________________
> 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

Benjamin Humphrey