documentation logo

[Andrew Mathenge]

A manpage repository is a good idea. I agree with Matthew that manpages are
documentation, but I see them as separate from general help. I refer to both
help pages and manpages. Help pages assist me in narrowing down a specific
issue I have which may ultimately point me to software from which point I then
need the manpage to figure out how to use that software. Anything written,
with a purpose, that is helpful can arguably be called documentation. But I see
the Ubuntu help system as very different from the Linux manpages.

I don't think that it's confusing that there's a separate manpages.ubuntu.com
site, but then again, having them in help.ubuntu.com/manpages might be
simpler since the site is already there.

If the ultimate goal is to have all documentation in one place (wiki,
help, manpages...)
then perhaps it's time to start consolidating around the help.ubuntu.com
domain.

Andrew.

On Fri, Sep 5, 2008 at 4:02 AM, Matthew East <mdke at ubuntu.com> wrote:
> Hi Nick,
>
> On Fri, Sep 5, 2008 at 8:40 AM, Nick Barcet <nick.barcet at canonical.com> wrote:
>> Matthew East wrote:
>>> 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?
>>
>> I might be wrong, but I think that the tool Dustin built does generate
>> the man pages automatically on a regular basis and it could be a bit
>> dangerous to have it running on an already heavily loaded web site (as I
>> suppose help.ubuntu.com is).
>
> Do you know how regularly? Obviously they would need to be regenerated
> for each release, but otherwise I would be surprised if it's necessary
> to regenerate them more than once a month or every two months: man
> pages don't really change that much between releases. But anyhow, I
> don't think that is a blocker, I'm fairly sure there would be a
> technical solution (like generating the html elsewhere and copying it
> over).
>
>>  I also think that the prefixing with
>> "manpages" allow to make a clear distinction between upstream provided
>> manuals and official (and specific) documentation the team has created
>> for Ubuntu.
>
> I don't really see that - these are Ubuntu manpages, in the sense that
> they come from Ubuntu and where an Ubuntu program is different from
> upstream, the manpage is updated accordingly. They are pretty clearly
> documentation, and as such belong on help.u.c.
>
> While they might be a different type of documentation, that is only a
> justification for making some kind of distinction in the UI, like
> including a tag somewhere on the page, not creating a separate
> website. Not everyone looks at the address bar, as we've discovered
> with other Ubuntu sites. Even for those that do, a url like
> help.ubuntu.com/manpages is equally descriptive.
>
> --
> Matthew East
> http://www.mdke.org
> gnupg pub 1024D/0E6B06FF
>
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>