+972 52-548-6969
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
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.
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!"
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
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
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".
Mark,
Thank you, that is very good to know.
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?
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