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,130 | Comments: 45,558

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. How to waste CPU and kill your disk by scaling 100 million inefficiently - 9 hours from now
  2. RavenDB Conference 2016–Slides - about one day from now

There are posts all the way to Jun 01, 2016


  1. The design of RavenDB 4.0 (14):
    26 May 2016 - The client side
  2. RavenDB 3.5 whirl wind tour (14):
    25 May 2016 - Got anything to declare, ya smuggler?
  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