If that elephant can do it so can You :)

That's why god gave us editors :) Plus with the open MEAP program, you are likely to get some good feedback, especially if you ask your audience specifically for the favor. I have always preferred to read more general, theoretical content in the text, and pick apart the full gory details in the downloadable code samples if required. When choosing between giving a piece of theory and filling the same space in the body of the book with a simple code listing, I'd go with the theory every time, as the technique can be picked up by studying a sample in about as much time as it takes to read the code listing (especially if it is commented), but theory is more subtle, and is much harder to extract from a codebase.

Downloadable code samples are a good start, but I think it's also important to have explanation to go with them. However, that doesn't need to be in the book itself. I don't know if you've already set up a web site as a companion to the book, but I've found that to be a really good way of keeping information which for whatever reason doesn't quite fit in the book, but which you want to make available anyway.

Jon

+1 for what Jon said.

I don't think it matter which way you choose as long as you are very clear about that choice in the title/cover.

It's really annoying to pick up a book on a subject you don't know much about hoping for a cookbook and getting a load of theory and vice versa. The trouble is you don't realise that for a while.

It might seem obvious to the author which side of that fence the book falls. However when you don't know much about a subject, it's not clear to you if the author is covering the core principles before diving into an example, or giving you a thorough grounding in the subject.

There are times when you want to just get something to work and when you want to fully grok it.

I am with Iain I like them both but it's always a good idea to know what you are getting into rather than after the fact.

I'd go for the basic level moving onto advanced, once the readers have finished they will have a good enough grasp of DSLs to learn on their own.

From a business perspective, your target audience would then be wider (that means more cash for you) and you probably wouldn't be directly competing with Martin Fowler's book. How many DSL books are available today? Especially ones aimed at beginners.

The Fowler book is expected in 2010. I hope to be done with the book by then.

Beginners and DSL don't really go together, you need to have a certain level of knowledge before you can go create your own language.

Yeah, I'm not talking about beginners to programming though, I mean beginners to DSLs. It's quite a vast subject, hence the balancing act you need to figure out now.

It's great to see Jon's comments, because I was going to refer to his book anyway.

The point I wanted to make is - there should be enough theory (specially because this is an advanced topic), and also sufficient examples (with some explanation, as is there in Jon's book).

Again, some samples should definitely be there in the book, so that the reader doesn't have to read from two different sources (a book and a website). Detailed examples or other information (as per Jon) is ok if kept in the companion website.

I know it will make a book bulky [ hence intimidating ;-) ], but sometimes its unavoidable. So thanks for the great book Jon and good luck Oren.

I feel your pain man. I am struggling through this myself right now... I just finished page 3 :)

Good luck.