Written design documents

Documents should complement code and speech

Each Agile process has its own philosophy about documents. Extreme Programming advocates usign no extra design documents at all and letting the code speak for itself. Running code doesn't lie, as any other document might.The behavior of running code is unambiguous.

But the code as design document does have its limits. It can overwhelm the reader with detail. Although its behavior is unambiguous, that doesn't mean its obvious. And the meaning behind a behavior can be hard to convey. In other words, documenting exclusively through code has some of the same basic problems as using comprehensive UML diagrams. Of course, massive spoken communication within the team gives context and guidance around the code, but it is ephemeral and localized. And developers are not the only people who need to understand the model.

A document shouldn't try to do what the code already does well. [...] Written documents should complement the code and the talking.

Documents should work for a living and stay current

Listen to the UBIQUITOUS LANGUAGE and how it is changing. If the terms explained in a design document don't start showing up in conversations and code, the document is not fulfilling its purpose. Maybe the document is too big or complicated. Maybe it is not focused on a sufficiently important topic. People are either not reading it or not finding it compelling. If it is having no impact on the UBIQUITOUS LANGUAGE, something is wrong.

Conversely, you may hear the UBIQUITOUS LANGUAGE changing naturally while a document is being left behind. Evidently the document does not seem relevant to people or does not seem important enough to update. It could safely be archived as history, but left active it could create confusion and hurt the project. And if a document isn't playing an important role, keeping it up to date through sheer will and discipline wastes effort.

Eric Evans, "Communication and the Use of Language", in Domain-Driven Design: Tackling Complexity in the Heart of Software, 37-39.