Documentation help

[Phil Bull]

Hi Manjul,

On Thu, 2011-06-16 at 13:21 -0400, Manjul Apratim wrote:
> I was not referring to any official notification for deciding what
> should be the portal for Ubuntu documentation, but as far as I am
> aware, the Community Documentation is the only resource for technical
> information regarding various aspects of Ubuntu? The Ubuntu wiki
> documents the hierarchy of the Ubuntu team and the working of the
> Ubuntu machinery, but is not the go-to area for technical support. I
> had brought up these issues in a previous email to the mailing list,
> which are part of the June archive. Please correct me if I am mistaken
> or have expressed a misconstrued opinion.

Not really, there is also help.ubuntu.com, which houses (official) HTML
versions of the installed system documentation, and also the Server
Guide [1]. You're right when you say that the "Ubuntu
wiki" (wiki.ubuntu.com) is for community coordination. It shouldn't be
used for end-user documentation.

I think we should work on making help.ubuntu.com itself a better portal
for documentation. It's OK as it is, but it doesn't really scream "hey,
user X, you can find useful help written specifically for you by
clicking here"! In my opinion, a good documentation portal which *does*
do this is the Mozilla (SuMo) website [2].

At the moment, we confuse our users by asking them to make too many
choices right from the start. We shouldn't necessarily be asking them
what version of Ubuntu they have and whether they would like to see
"official" or "community contributed" documentation as soon as they get
to the site. We should perhaps first get them to something that looks
relevant, and then let them worry about versions and "officialness" once
they're there.

Jim and I discussed this briefly at the recent Open Help conference in
Cincinnati. It probably makes the most sense to get the system help
building into the wiki, so there aren't two separate systems. This might
require a Mallard->Wiki markup processor, or wiki software which can
seamlessly integrate with static pages.

Another issue is the organisation of the wiki (h.u.c/c), which you've
personally done some great work on improving. The wiki tends to go
through cycles of being more or less organised. Perhaps a solution to
the problem is to use the "official" system docs as the top level
structure and then allow wiki pages as subpages of them. This would
allow us to guarantee that extremely important topics are well
maintained and displayed prominently, by having them in the system docs,
and then have less critical topics a little further down a well-defined
hierarchy.

> When I mean "fixed from scratch", I am really talking about scratch -
> fixed page by page. I have started by fixing the opening page of the
> Community Documentation, and as we speak I have moved on to the
> Installation section. I imagine most, if not all, pages to be
> re-written from a new-user's perspective, and make the Community
> Documentation at least as good as Arch Linux's. I shall not be alone
> in this, because many people on the forums are going to join in this
> effort - I have an ongoing thread for this:
> 
> http://ubuntuforums.org/showthread.php?t=1762598

I agree, and the work you've already done looks great. It's good to have
an idea of *why* the Arch wiki is so good, though. You need a strong
team of several editors who can quickly correct problems, a single
vision for the style and structure of content on the wiki, and lots of
contributors who can make sure everything is reviewed on a regular
basis. Essentially, everyone needs to have an idea of how the wiki
works. And you need this *in perpetuity* - the work of maintaining a
wiki is never done.

Our help wiki currently isn't like that - we have a number of good
regular contributors who do some great work, but there's not really an
overall vision for style and structure. Most of the topics there are
outdated, stylistically disparate, and were created by "drive-by"
contributors who were not acquainted with the set-up of the wiki. Many
are just information dumps. There have been attempts to impose order on
the wiki in the past that did OK, but I don't ever remember an attempt
which got the necessary buy-in to a single "way" of doing the wiki from
a large number of contributors which was kept up.

> If anybody complains about the state of the documentation, the first
> response from the team is naturally 'What have you done to contribute
> to it?' and that is right; the documentation is what a community makes
> it, and it is high time the community took action.

I agree with you here too. But if we're going to go through the whole
process of trying to clean up the wiki again (which we should!), let's
make sure we have a very strong idea of what we want it to be. We
shouldn't be afraid to make big decisions (like ditching lots of old/bad
content), change our processes (like restricting some edit access to the
wiki so it's not a free-for-all), or use new tools (like SuMo) if it
means we can get a more sustainable, user-friendly wiki out of it. But
for me, the most important thing is that whatever big changes are made,
they should be made after some careful thought and as a result of a
process which involves the whole community. Only then will we have a
single direction that will make it possible to have a sustainable help
wiki.

Thanks,

Phil

[1] - https://help.ubuntu.com/11.04/index.html
[2] - http://support.mozilla.com/en-US/home