documentation logo

[Matthew Paul Thomas]

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)---