documentation logo

[Matthew East]

Dustin,

On Fri, Sep 5, 2008 at 12:19 AM, Dustin Kirkland <kirkland at canonical.com> wrote:
> On Thu, Sep 4, 2008 at 5:22 PM, Matthew East <mdke at ubuntu.com> wrote:
>> Wow, you've kept that quiet! Is there any reason you're not using
>> help.ubuntu.com for this?
>
> Hey Matt-
>
> It wasn't meant to be a secret.  I posted the initial RFC here, which
> wasn't met with much enthusiasm:
>  * https://lists.ubuntu.com/archives/ubuntu-doc/2008-May/010891.html
>
> In any case, I've been working on it, and all of the source is
> available for view/review at:
>  * https://launchpad.net/ubuntu-manpage-repository
>
> I've been working with LaMont Jones of Canonical IT to get it
> production ready at:
>  * http://manpages.ubuntu.com
>
> And a redirect at
>  * http://help.ubuntu.com/manpages
>
> I've been running the test/demo on my little home server (not suitable
> for world traffic), but the real, production one should be up in a few
> days.  I'll blog about it, and announce here ;-)

I've had a look at the test/demo and it looks pretty good to me. Don't
get me wrong: I like it, and it's a good thing that you ran with the
idea yourself and took the initiative to get it done. However, the
fact that we haven't been kept in the loop as you progressed the
project has come as a bit of a surprise to me, because there are some
issues that need discussing here.

In this case, there isn't any doubt that the utility is a useful one:
it's a great idea as those who responded to your initial request for
comments agreed. But there is one important question: why does this
project warrant a separate website, as opposed to going directly into
help.ubuntu.com?

Starting a new website under the ubuntu.com domain has traditionally
been a big deal in the Ubuntu community. That's because a safe default
position is that it's a bad idea to create a new site rather than use
an existing one unless an existing one isn't good enough or there is
another compelling reason for a new site. I remember that when we
wanted to create a wiki at help.ubuntu.com and move documentation off
wiki.ubuntu.com, we spent several months working on the spec, took it
to the Community Council, who rejected the idea. That was
disappointing, but I ultimately understood that the reason was because
we hadn't made a compelling enough case to do it, and they were
rightly concerned about new websites confusing users and developers.
We reworked the spec, took it back, and finally got approval to do it.

I'm not saying you need to do something similar here, but I do think
you need to make a case for a separate website. For me, the manpages
are documentation, and they should go on the same website as other the
rest of Ubuntu documentation: help.ubuntu.com. Creating a new website
means that help.u.c will no longer be the unified documentation
resource that it was intended to be, and users will need to keep two
sites in mind.

You've driven this project, so you have a much better understanding of
its needs than I do. So it may be that there are genuine reasons for a
separate website with a new subdomain, which we don't know about yet!

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