"Official documentation" vs. "Community docs"

[Matthew East]

Hiya,

On Sun, Jun 8, 2008 at 12:54 AM, Matthew Paul Thomas <mpt at myrealbox.com> wrote:
> On Jun 7, 2008, at 9:31 PM, Matthew East wrote:
>> I think what you're raising indirectly is the fact that a guide to the
>> secondary way of installing Ubuntu appears on the homepage of
>> help.ubuntu.com, whereas a guide to the primary way doesn't appear. A
>> better way to present installation documentation would be to use this
>> page from the help wiki -
>> https://help.ubuntu.com/community/Installation - and link to the
>> alternate CD guide from there.
>
> I think the underlying problem here is that <https://help.ubuntu.com/>
> is a silo, an exact reflection of the help shipped on the CD, while
> <https://help.ubuntu.com/community> is a separate silo. This forces
> readers into a choice between "Official Documentation" and "Community
> Docs", when they have no idea which of these two will be more likely to
> answer their question. (Neither of them seem particularly hopeful:
> "Official Documentation" evokes bureaucracy, while "Community Docs"
> sounds like a neighborhood medical clinic.)
>
> It's useful to make a distinction between help that has been reviewed
> for accuracy and help that has not, but I think the current way of
> doing it -- by making them separate top-level sections of the Web site
> -- is unhelpful to the people who want to read it. (I'd prefer a
> friendly disclaimer at the top of unreviewed pages.)

Yes, sorry - that is what I was getting at too. I've wanted for a long
time to merge the two sites into one site that distinguishes better
how reliable a particular page is, so that the system documentation
would appear as part of the wider set of documents on the help wiki,
but be given a high reliability rating. That's what I meant in my
second post when I said:

"I think we should definitely find a way for the "official" docs to
interact better with the wiki docs. Maybe we can move forward in this
release cycle with the idea of merging the two, and have a single site
which explains to users how reliable each page is."

> How could this problem be solved? How could the topics listed on
> <https://help.ubuntu.com/> become a *superset* of those that appear on
> the CD, rather than an exact copy that forces all other help to be
> listed on a separate page?

I think the basic solution to this is to have a Moin wiki at
help.ubuntu.com which houses all the online documentation, whether
"official" or not.

There are a number of technical/policy issues to address. Here are
those that I can think of:

1. Do we separate the system documentation from the other pages or
simply try to blend them into the rest of the wiki organisation? I
have always thought that we should try and blend them in somehow. I
recall though that Jordan had a different idea once about having a
separate subpage or subdirectory to house them.
2. How do we render the "official" documents? This could be done
either by way of an xml->moin markup conversion, or by way of an
xml->html conversion (as we currently do) and then use an HTML plugin
for Moin. We could also try and automate the publishing process by
using the "editmoin" program.
3. How do we get over the fact that the "official" documents are
directed at one particular version of Ubuntu, whereas for the wiki
documents any difference between versions of Ubuntu is generally
explained in the body of the document. I don't really have any ideas
about this, what do people think?
4. Do we lock down the official documents (i.e. make them impossible
to edit) or not? I think we should - simply because not doing so would
create a difficult delta between our xml based repository and the
online pages.

I suspect we need to seriously brainstorm the above questions and
maybe draw up some kind of mockup for how it might look.

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