the user guide is written pretty well imo http://overtone.github.io/docs.html
totally agree, and it's a great effort! At the moment it stops when it starts getting really interesting for me though 🙂
I'm still working on it, just started 2 months ago, I'm waiting for an old-school overtoner to give me a hand writing it. But I think it's exactly what's missing in the docs, understanding of synthesis, time and shapes, something that's language neutral, and sadly expected knowledge. Hope to start writing about the macros and functions of overtone soon.
@hlolli I've read through what is there and I really appreciate the work that went into it, I think it might be exactly what's needed 🙂 cheers!