Developer review of documentation

[Matthew East]

Hi,

(Please don't cc: me to list email, I read the lists I post to)

> On Tue, 2006-11-28 at 11:13 +0000, Matthew East wrote:
>> We'd need to make a list of the key documentation to be reviewed (this
>> could include key system documentation, *and* key wiki pages), and
>> potentially identify the relevant developers who might be able to lend a
>> hand.
>>
>> How does that sound as a vague plan?
>
> There are a few ways of resolving this problem. Although your experience
> getting developers to lend a hand was positive, that surprises me - I
> would have thought the developers would be too busy for documentation.

A number of developers were distinctly helpful and suggested improvements,
in particular to the server and graphics card material. And Matt mentioned
in his earlier post that he is prepared to allocate some developer
resources to this task, so that sounds really positive.

> To me it seems we need to enforce the concept of a moderated knowledge
> base (which is what help.ubuntu.com seems to be). Wikis are great tools
> for collaboration and for temporary events and issues, but more solid
> information needs to live in the knowledge base. I would encourage the
> doc team to flag up items on the wiki, check them for grammatical and
> technical accuracy and merge them into the knowledge base.

I disagree. As I explained in a previous post, there is actually little
point separating out "solid" (or, as expressed elsewhere on this thread,
"official") information from material produced on the wiki, because the
reality is that there are many different degrees of solidness, and
further, to the extent that it is possible to distinguish between solid
and non-solid, that distinction doesn't match up with a distinction
between information produced/checked by the documentation team and
information produced by the community on the wiki.

The correct solution, in my opinion, is to ensure that users can find all
information (regardless of who contributed it or checked it) in the same
place (entitled, for example, "help.ubuntu.com"), but establishing a
really great system of quality assurance that reflect not simply a
solid/non-solid distinction, but all the different degrees of solidness
out there, and informs the user accurately of how reliable the page they
have found is. This is the technique used by the most successful
community-powered knowledge base around, Wikipedia, and it works.

Splitting up resources in the name of a distinction between
solid/non-solid (or official/non-official, or safe/unsafe) won't help,
because (a) the distinction is really just an oversimplification anyway,
and (b) it means that users need to undergo a multiple searching
procedure, wasting their time.

Another point to get away from is the idea that using a "wiki" as the
basis for a website prescribes a particular form of collaboration (i.e.
"free for all" collaboration). A "wiki" is just a website, which uses
particular software. Most wiki software, including the one used by us, is
powerful enough that we can define the method of collaboration that suits
us (by access control or other techniques), rather than a method of
collaboration being imposed on us.

So in the long terms I'd really like to see both our wiki documentation
and our system documentation sharing the same namespace at
help.ubuntu.com, making it searchable in one go. I have the feeling that
this would also have a really beneficial effect on contribution. In order
to make it happen though, we need to establish the effective quality
assurance system described above, for which the spec
https://wiki.ubuntu.com/HelpWikiQualityAssurance exists. We're also
dependent on certain technical barriers being overcome.

I'd really appreciate feedback and ideas on any of this.

Matt