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

[Eric Weddington]

> -----Original Message-----
> From: 
> address@hidden 
> [mailto:address@hidden
> org] On Behalf Of David McNab
> Sent: Friday, March 02, 2007 11:52 AM
> Cc: address@hidden
> Subject: Re: [avr-gcc-list] gcc-avr/avr-libc wiki
> 

> > I'm still concerned that helping with the "golden" 
> documentation might be an 
> > even better idea, but I don't know how feasible that is.  
> Or, would the 
> > maintainers of the "golden" documentation abandon that in 
> favor of the Wiki?
> 
> The 'golden' documentation, as you call it, consists mainly of the
> Doxygen-generated docs, with a few hand-written helper pages 
> tossed in.
> 
> The helper pages really need to be reorganised and added to. For
> example, entire subjects are covered in brief in the FAQ, where they
> should arguably be given their own pages and fleshed out in 
> more detail.
> 
> The advantage of a wiki is that it's a great medium for a lot of folks
> to do a little work each, instead of privileged-access html 
> pages where
> a few folks have to do a lot of work.


I agree with you that the avr-libc documentation is lacking. Yes, the
"helper" pages needs to be reorganized and added to.

The issue always has been about *volunteers*. It has nothing to do about
"privileged-access" html pages. The avr-libc project has never had a high
bar for entry, and it has consistently accepted help whenever it has been
given. The problem is that there are precious few people who are willing to
take the time to learn what it takes to truly contribute to the project.

For example, the current documentation is done via this Doxygen tool. It's
not a perfect tool. Many of us on the project have had many frustrations
with it. But we've gotten it to work in a certain way. Therefore if one
wants to contribute to the official avr-libc user manual, then one needs to
learn Doxygen, and also how to build the avr-libc project to test that
Doxygen documentation. That's the only barrier to entry. Please! By all
means, if you want the avr-libc manual to improve, please provide patches!
:-)

I'm sure that there are some people who will say that doing that is too
difficult, and that a simpler method such as a wiki is better. There are
places for both an official user manual, and for a wiki. But a wiki should
never be confused for a user manual. Any attempt to do that will very likely
fail. I have seen many projects try to do just that (wiki as user manual)
and it has never worked.

Now, AFAIK, AVR Freaks will be putting up a wiki. I don't know exactly when.
But that's seems like the best place for a wiki as there are many users
there, and AVR Freaks is a website that will not go away, and it has many
other advantages as well.

As to the language issue, one has to be careful with "accepted
colloquialisms", as they are, well, only accepted colloquially and not
universally. ;-) Being a native English speaker in America I can tell you
that these colloquialisms:
Doco - Looks absolutely silly and vaguely derived from Italian.
Docu - Looks like one letter too many.
Doc - Is perfectly acceptable as a singular document.
Docs - Is perfectly acceptable as plural documents.

But if one wants to effectively communicate, then it is better not to use
colloquialisms at all and just call them all "documents" as there is no
ambiguity and we wouldn't be having this discussion in the first place.

Eric Weddington