I think this can be applied to code reviews. We tried something like that.
During a code review the reviewer(s) would read the code. Whenever anyone asked a question to get clarification, it was seen as a symptom of code that needed to be more ledgible.

Perhaps not writing a book first, perhaps looking back a "literate-programming"...

The point is that a "good" implementation is very often far away in its logic from natural speech anf the underlying thinking. When I write documentation I usually refactor code as I figure out an understanding that hadn't been obvious before, it goes thus in both directions: The real-world code teaches me something about the logic that hadn't been clear when designing the program.

We made recently a small project where we wrote the documentation as the implementation advanced. We refactored both on different levels and ideas from a better understanding went back into the system. It was quite a fun to work like this (we didn't do this intentionally, originally we had to waste some time in a useful manner until the next specs drippled in).

Now I finally understand the idea behind literate programming....

When answering questions on mailing lists about 'how do I do X with Y', I often find myself embarrassed about how complicated an answer can be. It's at that point I find myself committing some patches as it's far simpler to fix the problem, than to explain it.

It reminds me the proposal of Laurent C : "When you create an API, before implementing it, write the tutorial explaining how to use it."

Yet today, it's not a wide spread habit. Not only the quality of the API suffers from it, but better the people who would like to evaluate the API and/or the programming model, more early and easily.

Well, you see my point: i'm evaluating a library currently in development, and there isn't any tutorial... :-)

Vincent, if you really want to make a good documentation, is a paper book the best solution ? Do you never say to you: it is too much work, or there is a too big Overhead ? The Overhead comes from the fact that you have certainly an interesting subject, important maybe also, but the paper book you are preparing has to a nice history, nice and easy, or you will not be read.
The Overhead comes because you do not have hyperlinks that let any Reader navigate through the history, in the sequence he needs and he wants. So you have to find the tips to help him and to interest him. This is very hard, congratulations to you to make it ...

Mabe you could give also an hyperlink version, that will let Reader make their own navigation more in line with the interest he has on the different parts or with the Time he has.

Again, Bon courage !

On the other hand I really understand that your approach gives a superior quality of your document and of your framework in the same time.

I've come to the same conclusion lately, from trying to reuse code from open source projects in my own project. In terms of reusability, code without an explanation is worse than useless because it can eat up your time trying to find out if it does what you need. I'm a satisfied user of many OSS projects, but I'd like to also re-use them, as a developer.

I've written a tool, JCite, which supports this idea nicely. It lets you integrate snippets of code as examples in your docs, _cited from actual use-case tests_. That way, you ensure the integrity of the sample code. Also, I am thinking of a "tripwire" system that will flag docs citing tests which have changed. This will alert you to review the surrounding docs.

http://arrenbrecht.ch/jcite/