Ayende @ Rahien

Refunds available at head office

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
09/26/2008 08:39 PM by
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
09/26/2008 09:46 PM by
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
09/26/2008 10:14 PM by
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
09/27/2008 02:47 AM by
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
09/27/2008 02:49 AM by
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
09/27/2008 02:51 AM by
Ayende Rahien

Mark,

Thank you, that is very good to know.

Dru Sellers
09/29/2008 11:57 PM by
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
09/30/2008 06:00 AM by
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

Comments have been closed on this topic.