RE: [avr-chat] AVR Documentation

[Eric Weddington]

> -----Original Message-----
> From: address@hidden 
> [mailto:address@hidden
>  On Behalf Of Colin O'Flynn
> Sent: Sunday, March 11, 2007 12:13 PM
> To: 'avr-chat'
> Subject: [avr-chat] AVR Documentation
> 
> Hello,
> 
> AVRFreaks has a new Wiki - would it be reasonable to use that 
> as a central 
> point of avr-gcc related documenation?
> 
> I ask as for a while I've been working on a "guide" to the 
> avr-gcc toolchain. 
> There actually isn't too much yet, don't get excited ;-)
> 
> However this would just be another document floating around, 
> with the source 
> doc somewhere (it's written in openoffice right now). Having 
> it in a Wiki 
> might make it be a little more up to date, since it's very 
> easy for other 
> people to change it.
> 
> Before commiting time to moving the stuff into the Wiki 
> though, I wanted to 
> see if the avr-gcc community would use the wiki?

I see the wiki as being useful for *additional* documentation, or
information that is still *live* or temporal in nature. However, any
*official* documentation should really be with the upstream projects such as
avr-libc.

The folks at avr-libc took a lot of time (years ago) to take the best of the
individual documentation that was floating around at the time, and integrate
it into the avr-libc user manual, so it could be a central place for
documentation on the overall AVR toolchain.

What I don't want to see is the community going that way again, with
fragmented documentation spread all over individual sites. (Go here for X,
go there for Y, oh, you need to do Q, go to W to do that...)

If there are problems with the avr-libc documentation, and I don't doubt
that there is, then *please* let's get it fixed! It is not some exclusive
club that is difficult to join. We are very open to changes. And we're even
open to changes that would totally rewrite the existing documentation in a
new format, especially if we thought that that format had advantages.

There are just a couple of things that we request of the avr-libc
documentation that might put a somewhat high bar for entry:
- If changing formats, then it has to be complete, i.e. it has contain
everything that it does now.
- It has to be a cross-platform documentation format. So this limits the
output format to something like PDF and HTML. The input format gets a little
more tricky because the tools used to build the documentation has to work
across all platforms.

So, Colin, going back to your specific issue: It would be great if you would
be willing to include your guide into the avr-libc user manual. Yes, we need
to see if we can do some reorganization of the "Additional Pages". I think
we can because years ago I had a patch that was able to reorder the pages.
We definitely need to have a guide or tutorial about the toolchain and how
to use it, especially for new users.

Eric Weddington