Re: [avr-gcc-list] gcc-avr/avr-libc wiki

[David McNab]

On Thu, 2007-03-01 at 07:14 -0500, Graham Davies wrote:
> David McNab write (in part):
> 
> > If everyone reading this message can stick up just one page ...
> > Let's get some really great and complete gcc-avr/avr-libc doco.
> 
> I'm just wondering:
> 
> Who hosts avrwiki?  How do we know it won't suddenly go away?  I've had a 
> bad experience working on a Toyota Prius site that was hacked and then 
> disappeared taking hundreds of hours of community work along with it.  How 
> can we be sure that work we put into avrwiki will be durable?

That problem could be easily overcome - stick up a wiki at the avr-libc
home page - http://www.nongnu.org/avr-libc/

> Who will organize, scrub and correct minor errors?  Who will set policy (for 
> example, decide what is an error and what isn't?

Correct me if I'm wrong, but that sounds like "we'd better not have a
wiki, because I can't think of anyone who's got the time to ensure it's
perfect".

Wikipedia is full of problems - systemic bias, errors, conflicting
agendas etc, but it's a heck of a lot better than having no wikipedia at
all.

> The AVR GCC page, for 
> example, calls avr-gcc "gcc-avr", which will mess up searches.

I thought that 'gcc-avr' was the correct terminology. If it's not, then
the Ubuntu packages 'gcc-avr', 'binutils-avr' etc are incorrectly named.

> What exactly 
> is "doco"?

It's an accepted colloquial shortening of the word 'documentation'.

> Is the spelling, capitalization and punctuation currently on 
> this site acceptable?

> I suppose my concern is that since the documentation we're talking about 
> does exist, is maintained and you can find it with reasonable effort,

For a newcomer, the effort involved is much more than 'reasonable'. You
can't always assume that readers have your own level of familiarity with
the subject.
 
> wouldn't putting up a second source of information oblige us to adhere to at 
> least the same standard of quality as the originals?

Not necessarily. Quality is always a goal to shoot for, but fears of
lesser quality are not in themselves a reason to squash the very notion
of a wiki.

Anyway, sorry to say this, but the 'originals' to which you refer are
not actually a very high quality of documentation. They're kind of ok,
but that's all. If you don't believe this, then get a professional
technical writer to review the site and give their opinion.

> If we don't, we'll be 
> doing the community a disservice by hiding the real documentation behind 
> something of lower quality.

That doesn't make sense - especially if the wiki pages feature generous
linking into the avr-libc pages. In such a case, a wiki, even if it's
inferior by your own quality standards, will make the avr-libc homepage
doco^Humentation (sorry!) more quickly accessible and with less effort.

And if there are any critical pages you're worried about, you can always
sign up to receive edit notifications by email, and tweak here and there
if there's something you don't like.

Cheers
David