documentation logo
Matthew Paul Thomas
mpt at myrealbox.com
Mon Sep 8 01:50:53 UTC 2008
On Sep 5, 2008, at 4:05 PM, Dustin Kirkland wrote:
> ...
> 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,
It's not clear to me from manpages.ubuntu.com. There's a big "Ubuntu"
logo at the top, and no other prominent credits. Sometimes an
individual manual page has an "AUTHOR" section, but I haven't worked
out whether that's the author of the software, the manual page, or
both.
I don't think any of that is an actual problem. But it does show that
putting the pages on a separate site doesn't make attribution clearer.
> 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.
Is the primary purpose of manpages.ubuntu.com to give credit to
upstream authors, or to help people using Ubuntu?
If it is to help people using Ubuntu, I think it would help more people
if the navigation was integrated with that of help.ubuntu.com.
That doesn't necessarily mean putting it under the same subdomain.
Doing that might make unifying the navigation easier, but (as you've
suggested) it might make publishing the information at all more
difficult.
> The documentation at wiki.ubuntu.com is User-contributed.
>
> The documentation at help.ubuntu.com is Documentation-Team-contributed.
>
> This documentation at manpages.ubuntu.com is Generated from the
> manpages already included in each and every .deb shipped in main,
> universe, restricted, and multiverse.
>
> To me, those are 3 very distinct forms of documentation.
Who contributed the information is mostly irrelevant to people
accessing the information. (It's somewhat important for establishing
trust, but upstream contributors aren't obviously more or less
trustworthy than Ubuntu contributors.)
wiki.ubuntu.com and help.ubuntu.com are separate because the former is
for information about Ubuntu development, while the latter is for
Ubuntu help.
> ...
> I consider a wider scope of Ubuntu Documentation to include:
> * Formal Docs
> * Official Docs (help.ubuntu.com)
> * Wiki Docs (wiki.ubuntu.com)
> * Man Pages (manpages.ubuntu.com) <------- N E W
> * Blueprints (blueprints.launchpad.net)
> * User-level Discussion
> * Answers (answers.launchpad.net)
> * Forums (ubuntuforums.org)
> * Mailing Lists (lists.ubuntu.com)
> * Developer-level Discussion
> * IRC Logs (irclogs.ubuntu.com)
> * Bugs (bugs.launchpad.net/ubuntu)
> * Code (code.launchpad.net)
> ...
Nobody wants "documentation". They want to know why their screen goes
blank occasionally, or what happened in last week's Technical Board
meeting, or where their nearest LoCo team is, or how they can help with
firewall implementation, or whether their computer's wireless card will
work in the next version of Ubuntu, or what sort of alternatives there
are to "grep", or how the live CD is assembled, or what date Canonical
will stop issuing updates for 7.10.
When they're looking for this information, usually they know whether
it's about development or help. Usually they know whether something
they want help with concerns installation or networking or
communication or printing or terminal commands. Usually they know
whether their networking problem is about a local network or dial-up or
broadband or Bluetooth or 3G. And so on. What they don't know is what
magical property makes one thing "documentation" and another not. For
an Ubuntu Web site to refer to "documentation" is about as useful as a
physics textbook referring to "stuff".
> ...
> 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.
> ...
All other factors aside, I think it would be good for the domain name
to look less like it belongs to an online dating site. Would it be
difficult for this separate server to serve help.ubuntu.com/manuals,
instead of having its own domain?
Cheers
--
Matthew Paul Thomas
http://mpt.net.nz/
---AV & Spam Filtering by M+Guardian - Risk Free Email (TM)---
More information about the ubuntu-doc
mailing list