Ayende @ Rahien

Hi!
My name is Ayende Rahien
Founder of Hibernating Rhinos LTD and RavenDB.
You can reach me by phone or email:

ayende@ayende.com

@

Posts: 5,949 | Comments: 44,546

filter by tags archive

Chapter 11 is done, or the tale of meta documentation


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.


Comments

anonymous

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.

Thanks,

-Mark

Ayende Rahien

anonymous,

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

David,

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

Mark,

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.

FUTURE POSTS

  1. The RavenDB Comic Strip: Part III – High availability & sleeping soundly - 11 hours from now

There are posts all the way to May 28, 2015

RECENT SERIES

  1. The RavenDB Comic Strip (3):
    20 May 2015 - Part II – a team in trouble!
  2. Special Offer (2):
    27 May 2015 - 29% discount for all our products
  3. RavenDB Sharding (3):
    22 May 2015 - Adding a new shard to an existing cluster, splitting the shard
  4. Challenge (45):
    28 Apr 2015 - What is the meaning of this change?
  5. Interview question (2):
    30 Mar 2015 - fix the index
View all series

RECENT COMMENTS

Syndication

Main feed Feed Stats
Comments feed   Comments Feed Stats