[Arm-netbook] policy for wiki and mailing list

[Alain Williams]

On Sat, May 19, 2012 at 12:28:47PM +0100, David Given wrote:

> Posts to a mailing list are timestamped, attributed, are easily
> searchable with any common search engine, and occur in context with the
> discussion that prompted the post.

If context is important, you can also put into the wiki a URL that is part of
the thread where whatever topic is being discussed. There is the URL of your
mail that I am replying to:

   http://lists.phcomp.co.uk/pipermail/arm-netbook/2012-May/003641.html

The URL to the list is in the foot email from the list.

The wiki is timestamped (look at recent changes), attributed (look at recent
changes), well indexed by search engines. The items in the wiki can structured,
if you can't find something then add an index to the wiki.

I have to agree with Luke. The point about all of this is to communicate to a
common goal. What is the point of you saying something if people do not remember
it? If what you say is hard to find then you have wasted your time.

If you don't understand something, then why not create a page on the wiki that
has a decent title & just says 'No information available'. It only takes a
couple of minutes to add stuff to the wiki, so do it and make life better for
all.

Not everything needs to be immediately added to the wiki: delivery dates for
something, that is something that will be out of date in a fortnight.

> Information in a wiki is none of the above. It's just a random
> collection of stuff with no intrinsic order and no context.

In that case: help to add an index to the wiki.

The wiki will never be perfect, but it is better than nothing.

> I've dealt a lot with the NSLU2 project. They have a big wiki, and
> encourage people to add to it whenever the solve a particular problem.
> In theory, fine. In practice, the wiki is a vast pile of fragmented
> gibberish. It's impossible to find anything and what you can find is
> mostly hideously outdated and frequently simply *wrong*.

If stuff is outdated then people are not doing what they should keep it up to
date.

> Wikis are great for documentation. They do not make documentation happen
> by magic. Encouraging people to add every little item of trivia to the
> wiki will not form documentation --- instead you'll just get a big pile
> of trivia.
> 
> I agree that things need to be documented... but only once they've been
> adequately discussed on the mailing list.

Do the two. I worked with Luke on another project a couple of years ago. The
wiki was frequently incomplete, but we updated it as we worked things out.
It was far easier to look through the wiki than to grep the mail list; but it
did need some discipine by people of an adult disposition, people who understood
that the aims of a common goal.

-- 
Alain Williams
Linux/GNU Consultant - Mail systems, Web sites, Networking, Programmer, IT Lecturer.
+44 (0) 787 668 0256  http://www.phcomp.co.uk/
Parliament Hill Computers Ltd. Registration Information: http://www.phcomp.co.uk/contact.php
#include <std_disclaimer.h>