Hi
nice work! This is really interesting to see, as it mans that an open-source project like Arduino will soon have documentation similar to or equivalent to the leading commercial product in this area, the Basic Stamp. That a project without any employees could create something so big is really a significant accomplishment.
That said, I agree that it is really a beginning programmer's reference rather than a guide to the the entirety of approaches to the Arduino. A few suggestions:
-
Pictures for the tutorial pages. The schematics are really great, but reading schematics for beginners is sometimes a bit of a conceptual leap. As Tom Igoe has shown so well, photo plus schematic plus code activates the learner on the visual, tactile and reading levels. Everyone learns differently; one educational theory called VARK proposed that there are four modes: visual, aural, written and kinaesthetic ( i.e. doing). With pictures added to what you have, the only learning mode missing is aural-- i.e. someone there to actually explain it in words.
-
A bit of an introduction. If this is programming-centred, then perhaps there should be more of an intro to programming structure than there is now.
If it is to be a bit more hardware-centred, something like Jim Campbell's model for interactivity would be really good. See this page. He is very non-proprietary about his designs; if you asked him you could probably just copy what he has there. -
Examples. It never hurts to throw in a photo or two of a completed project, so that the highly technical aspects of doing this kind of thing are punctuated with a project that gives the reader an idea of the possibilities of the knowledge they're acquiring.
-
Plain-language headings. When someone sees the word "structure" all by itslef, their mind looks for their current knowledge on the work-- they try to associate it with a meaning. The headings should perhaps then be more explanatory, as in "the structure of Arduino Programs". With so many "variable", i.e. new words and concepts for the beginner to learn, it pays to make the explanation simple, so that the learner can more precisely on the subject. For example, "int the integer variable" is more efficient at communicating the topic than plain "int"
Anyway, this must have been a huge effort, and you are to be congratulated... you get the Programmer is responding trophy.
Best
Daniel
PS: I added a "manuals" page to the Playground...