I love that idea. I was looking as the "documentation" for a web-framework yesterday. All I was getting was tutorials and videos, nothing that explained to me how the damn thing works. Most of my questions would have been answer more quickly with a simple "Here's how it works and here's the API".

A few times a week I browse the mailinglist archives for the OpenBSD cvs and misc lists. Why some people may see it as rude, I find it refreshing when the developers tell people that reading walkthrough, tutorials, quick start guides and googling isn't a substitute for learning how things work. Sadly few products/projects make it easy to learn how things work and focus solely on "here's how you do X/Y/Z. Just tell me how it works and I'll figure it out.

I honestly think that this "left-brain centric" approach is to blame for a lot of people picking wrong solution for the problems. Of cause people should know better and get a more in depth knowledge before picking a tools, but realistically that doesn't happen as often as we would like.

I think there would be a large audience for the type of documentation that your suggest and I believe that it would a lot of people, my self included, to be better developers.

Please email me personally when you have something. (Contact info is in my profile.) This might be useful to my son who bitches endlessly about how impossible it is to learn code because no one actually explains anything useful/meaningful. I taught him math conceptually to get past the fact that numbers don't compute for him and that worked well. If he likes it, I will be happy to spread the word a smidgeon. I've talked to him a little about HTML and CSS and he was like "That actually makes sense! No one fucking* tells you this stuff. You can't find this info on the web. (etc)" But my knowledge of code is extremely limited.

Thanks.

* Unlike me, my son does not typically swear a blue streak. This tells you how frustrating he finds this.

I don't know that it's a right-brain vs left-brain thing so much as a preference in learning style: do you prefer to get the big picture first and then make it real with small chunks, or do you prefer the small chunks first and building the big picture afterward? Although I prefer the big picture first, I've learned it's really useful to bounce between the two modes on a given chunk of learning to make sure I really understand what I thought I understood.

Of course, when you first begin programming the computer is annoyingly finicky about those small chunks; unlike IMs, picky little details like punctuation, spelling, and syntax demand your attention before you can get experience with the big pictures.

It's worth trying!

thanks for the encouragement =). I am working on one now for jekyll but it's not finished yet.