The thing is, most such “places” were built with good intentions all along. But not just code can be refactored. Processes too. Organizations too. If you see that your developers are grumpy because they have too many places to do to find information, send them to this blog post! They might figure out what there problem is, and even get ideas how to solve it!

In any case, I think this is the first time I understand why developers are grumpy all the time.

I have often referred to this principle as “optimizing for programmers’ time” or sometimes “for programmers’ sanity” (as opposed to the common optimizing focus of time, memory, space…)

Established concepts like encapsulation and patterns can go a long way towards it (and provide a framework to evaluate one’s code by) but there is also a certain level of intuition, and even beauty in really good code.

I agree on the documentation bit, especially when you have distributed teams working in different regions. You need a place for the discussions and decisions to be centralized to ensure that everyone is on the same page. My vote goes to a wiki type of solution.

The sentence on the cost of changes was hastily written: I rephrased it to: “the cost of changing a system may not grow exponentially as is commonly thought”. The idea is that, if you follow XP practices, and particularly TDD and refactoring, the cost of changing the system will remain stable.

As for what documents I recommend… Once you understand that you should avoid the need for documents in the first place (for example, by keeping the design and system simple and intuitive), there remains situations where you cannot/should not avoid them. Prompting/starting thinking is one of them. Also, customers are often outside our buildings, and we cannot meet/chat as easily as we’d like, especially since decisions involve so many people in large organizations. In that case, you want a tool that makes it easy to create an initial version (with lots of pictures and diagrams), but also for changes to appear clearly (since there will be changes!). I have not yet found my dream tool for this. But I recommend newer collaboration tools, such as shared enterprise wikis. Confluence is a good product (not for the diagrams, unfortunately). Or Sharepoint. On my list of things to try out are: Writeboard and Google Wave.