+972 52-548-6969
DSL: Tests as documentation
I have several DSL that have no documentation beyond their source and the tests. They are usable, useful and have been of a lot of help. However, I have run into situations where I, as the language author, could not answer a question about the language without referring to the code. I strongly recommend in investing the time to create good documentation in your DSL.
Even if you are using a Behavior Driven Design flavored tests, it is not quite enough. Those types of tests can help make it clear what the language is doing, but they are not the type of documentation that you can hand to an end user and expect them to start using the language.
Even if your users are developers, it is not nearly good enough approach. It is your responsibility to make the system easy to use for the users, and documentation is a key part of that.
Handing them the tests is a good way to handle the complex cases, if your users are developers, but it is not a good way to reduce the learning curve.
Comments
So does that mean you are going to start writing some documentation now, or hinting at others to write it for you :)
Jonathon,
Me, writing documentation? Ain't gonna happen!
Oh wait, what is that book doing over there?
I rarely find this to be an issue with Boo. For the most part having my documentation / reference be runnable has been a boon..
Comment preview