documentation logo

[Matthew East]

Hi Dustin,

I'd better start by saying that I can see that this project has
reached such an advanced stage of implementation that these
discussions shouldn't be viewed as compromising it - I accept that
it's not helpful to stick an oar in that process at this stage.

I'm a bit disappointed that the docteam wasn't kept in the loop of the
progress of the project, because it would have been positive to have
these discussions at bit earlier (regardless of the outcome). So for
that reason I'm commenting anyway on some of your points below...

On Fri, Sep 5, 2008 at 4:05 PM, Dustin Kirkland <kirkland at canonical.com> wrote:
>> Starting a new website under the ubuntu.com domain has traditionally
>> been a big deal in the Ubuntu community.
>
> True, it certainly wasn't trivial!

I'm not talking about the technical steps required, I'm talking about
the need carefully to make a case for starting a new website rather
than using an existing one...

The technical aspects of the site that you've described clearly do
warrant a separate server for the generation process. I'm just not
convinced they warrant a separate subdomain for the static pages.

> The overwhelming majority of manpages is written by upstream authors,
> independent of Ubuntu.  I have a mild concern that some people could
> be misled that the Ubuntu Community "wrote" the 300K manpages served.
> That's clearly not the case, and very much a distinction from the rest
> of the content hosted on help.ubuntu.com and wiki.ubuntu.com, which is
> overwhelmingly written by the Ubuntu Community.

I have to say that I don't see the logic of this. The fact of using a
separate Ubuntu subdomain, as opposed to a subfolder of the existing
Ubuntu documentation website, doesn't per se mean that you are giving
more credit to upstream authors. The url is still marking it clearly
as an "Ubuntu" website. The only way to attribute an upstream author
is in the UI or text of the page. And that can be done regardless of
where you host the html.

Your argument seems to be that there is a stigma attached to
help.ubuntu.com that it is created by the Ubuntu community and won't
contain upstream material. I don't think that's necessarily the case
at all. We could easily include upstream documentation there in the
future, subject to proper attribution.

The idea of help.ubuntu.com is to provide a unified user documentation
resource for the Ubuntu community.

I think you've kinda accepted that to be desirable by talking about
the help.u.c integration solutions that you have planned, which I
appreciate.

> Furthermore, I think there are far more forms of documentation spread
> throughout the Ubuntu Community.

While it is true that there is information on other sites which can be
useful for users, such as information on bug reports, mailing lists
and so on, none of those sites other than help.u.c (and now
manpages.u.c) are specifically designed to provide information to
users. For our discussion purposes, I think it's worth distinguishing
between "documentation" and "information" on that basis, rather than
calling everything "documentation".

(Note that wiki.ubuntu.com - at least theoretically - doesn't provide
any documentation for users, it provides documentation for Ubuntu
contributors/developers.)

> I've posted here before about the
> Google Custom Search I've implemented for Ubuntu (yes, there are a
> number of others out there):
>  * http://people.ubuntu.com/~kirkland/search.html
>  * https://launchpad.net/ubuntu-documentation-search

I'm really keen on plugging a better search tool into help.ubuntu.com
- this is definitely a very important improvement we need to bring to
our users.

> I think there are decent reasons why the code that generates this
> belongs on a separate server, which we called manpages.ubuntu.com out
> of a lack of imagination ;-)  But I'd like to tie it to
> help.ubuntu.com in any way that makes sense.

That's appreciated.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF