Ayende @ Rahien

My name is Oren Eini
Founder of Hibernating Rhinos LTD and RavenDB.
You can reach me by phone or email:


+972 52-548-6969

, @ Q c

Posts: 6,124 | Comments: 45,474

filter by tags archive

Chapter 11 is done, or the tale of meta documentation

time to read 1 min | 189 words

Here it the table of content:

  • Writing the Getting Started Guide
    • Create Low Hanging Fruits
  • The User Guide
    • Documenting the Language Syntax
    • The Language Reference
    • Debugging for business users
  • Creating developer documentation
    • Outlining DSL structure
    • The syntax implementation
      • Keywords
      • Behaviors
      • Conventions
      • Notations
      • External Integration
  • Documenting AST transformations
  • Executable documentation
  • Summary

The chapter starts with...

Documentation is a task that most developers strongly dislike. It is treated as a tedious, annoying task and often falls on the developer who protests the least. One additional problem is that a developer trying to document his own work is often not going to do a good work.

This is not an aspiration against developers in general; the problem is that there are too many things that people who actually write the code takes for granted. And even in we ignore that, developers tend to write to developers, in a way that makes little sense to non developers.

That is true for me as well. And trying to document how developers should write documentation is... hard.

At least I can look forward for a really interesting Chapter 12.



Spelling is optional, but since this is meant for publication and won't be caught by a spell checker...

Did you mean "aspersion", rather than "aspiration"? "Aspersion" implies a false charge. "Accusation" makes more sense here, since you wouldn't accuse yourself of casting aspersions.

David S Anderson

Ah! In the context of all the financial turmoil here in the U.S., I see the headline: "Chapter 11 is done". My first thought was, "Dammit! They got Ayende, too!"

Mark Nijhof

Hey Ayende (Oren),

Just wanted to let you know how much I am enjoying your book, I just got it but I like your writing style and the topic is very interesting.



Ayende Rahien


Thanks, you are correct.

Luckily, I have the publisher that is going to have a professional run through the book and fix those type of issues, so the final book will not have them

Ayende Rahien


Yeah, I thought of that. That was funny since writing that chapter was so hard, I kept bemoaning, "this chapter 11 is killing me".

Ayende Rahien


Thank you, that is very good to know.

Dru Sellers

How can a DSL self document? Can it? I am finding great pleasure in my current development work, where I have the fortune to have some of the system document itself. These are the things I can do, and how they are used and so forth. Can this be applied to DSLs?

Ayende Rahien

Only in some very specific ways.

For example, you can probably create a language reference fairly easily, if you have a predictable language layout.

Beyond that... I don't think it would be very helpful

Comment preview

Comments have been closed on this topic.


  1. RavenDB 3.5 whirl wind tour: You want all the data, you can’t handle all the data - about one day from now
  2. The design of RavenDB 4.0: Making Lucene reliable - 2 days from now
  3. RavenDB 3.5 whirl wind tour: I’ll find who is taking my I/O bandwidth and they SHALL pay - 3 days from now
  4. The design of RavenDB 4.0: Physically segregating collections - 4 days from now
  5. RavenDB 3.5 Whirlwind tour: I need to be free to explore my data - 5 days from now

And 14 more posts are pending...

There are posts all the way to May 30, 2016


  1. RavenDB 3.5 whirl wind tour (14):
    29 Apr 2016 - A large cluster goes into a bar and order N^2 drinks
  2. The design of RavenDB 4.0 (13):
    28 Apr 2016 - The implications of the blittable format
  3. Tasks for the new comer (2):
    15 Apr 2016 - Quartz.NET with RavenDB
  4. Code through the looking glass (5):
    18 Mar 2016 - And a linear search to rule them
  5. Find the bug (8):
    29 Feb 2016 - When you can't rely on your own identity
View all series



Main feed Feed Stats
Comments feed   Comments Feed Stats