[peterb]

In my experience it is not one or the other. You can experiment first and then document, or vice versa. The point of documentation is "writing is thinking". The act of writing forces you to think through your ideas in ways that other modes of thinking do not. This is especially important when you are working on a team and need to share your ideas.

I agree that sufficiently detailed design documents are indispensable from code and should be avoided. However, clearly documenting the why, what and how of your work helps align everyone clearly. It also helps an individual clarify their ideas to themselves. It is hard to write clearly & succinctly. It takes time & practice, but I find it essential.