Chapter 11. DSLs and documentation

Documentation is a task that most developers strongly dislike. It’s treated as a tedious, annoying chore, and it often falls to the developer who protests the least. Furthermore, developers trying to document their own work often don’t do a good job. There are too many things they take for granted in their own code, and they tend to write to developers, in a way that makes little sense to non-developers.

At least, that’s what I say when I’m asked to write documentation. It doesn’t usually get me out of the task, but the problems are real.

Solid documentation is an important part of quality software. If the developers of the system are needed to handle routine matters, something is wrong. DSLs are no different in this regard. In fact, documentation is extremely important for DSLs, because you don’t have a friendly UI that you can explore using trial and error.

You also need to keep in mind that DSLs are still rare in the industry (although they’re a rapidly growing trend). Handing another developer a real-world DSL implementation will require some effort if the DSL implementation isn’t documented.

11.1. Types of documentation

11.2. Writing the Getting Started Guide

11.3. Writing the User Guide

11.4. Creating the Developer Guide

11.5. Creating executable documentation

11.6. Summary