Direction of the Ubuntu system docs

[Phil Bull]

Hi guys,

We have the following bug report open, requesting documentation for
Unity:

https://bugs.launchpad.net/bugs/600875

In light of this, I think it's time we discussed the direction of the
Ubuntu system docs. The package is becoming outdated - we've mostly been
in maintenance mode for the last few release cycles, and even that's
only due to the hard work and dedication of a couple of people. There
are a number of changes in Ubuntu and related projects that we're going
to have to adapt to and make some decisions about if we're to stay
relevant:

      * GNOME apps are switching to Mallard-based help, whereas we're
        using DocBook. In particular, the new GNOME Desktop Help is
        being written in Mallard and will have integration points for
        distros built into it. Mallard support in Yelp is also looking
        very good. If we stick with DocBook, we won't be able to take
        full advantage of this stuff. I hasten to add that staying with
        DocBook is a viable option - we can still link to the new GNOME
        stuff, and Yelp still supports DocBook - but we'll be missing
        out on some niceties that I think would really benefit us. (N.B.
        I'm biased; I'm a member of the GNOME Docs Team.)
      * Ubuntu will default to Unity rather than the GNOME 2.x or GNOME
        3.x shells as of the Natty release. It will apparently fall back
        to the GNOME 2.x shell if a computer doesn't have sufficient
        graphics support for Unity. We will be in the position where we
        need to support at least two shells, and the general desktop
        documentation (from GNOME) will be written under the assumption
        of another shell that we don't support. This is complicated
        because the shell the user is using defines basic interactions
        like starting an app, accessing files and settings, and even
        where the window controls are placed (Unity has a Mac OS X-like
        detached window menubar). I can think of ways of handling this,
        but it's a *lot* of work, and the most elegant solution (in my
        opinion) would require us to switch to Mallard.
      * The Ubuntu Manual project appears to be struggling [1]. This has
        been the most publicised Ubuntu user assistance effort for the
        past few releases and, though not an Ubuntu Docs project, it
        does overlap with what we are doing. Having two teams working on
        related projects, with both of them struggling for contributors,
        seems senseless.
      * Canonical are now asking for people to sign a copyright
        assignment agreement before contributing to Canonical-maintained
        apps. Practically, I think this means that they won't accept
        patches to packages if the patch author hasn't signed this
        agreement. It essentially transfers ownership of a copyrighted
        contribution to Canonical, and then grants you a broad
        usage/distribution license back. Personally, I am not
        comfortable with this sort of agreement, for a number of
        reasons. Others are likely to feel different. I've highlighted
        it because it could affect where we decide to maintain our
        documentation; if we put it in the Unity package, for example,
        it has to be covered by this agreement.

Given these changes, what do people think we should be doing with the
ubuntu-docs package? At the moment, we have some "getting started"
material, links to some general desktop documentation, overviews of
application installation and common applications, and a bit of hardware
troubleshooting. This is similar to what the Ubuntu Manual does, but in
a different format/writing style. We don't really have any installation
material either (mostly because I keep failing to work on it).

There are lots of directions we could go in, so I'm interested to hear
what people think.

Thanks,

Phil

[1] -
http://itigloo.com/2010/12/13/ubuntu-manual-project-progressing-slowly/
[2] - http://www.canonical.com/contributors

-- 
Phil Bull
https://launchpad.net/~philbull
Book - http://nostarch.com/ubuntu4.htm