Make sure all the "negative space" aspects of design are communicable in intent

See this doc: http://www.iasaglobal.org/document.asp?MODE=VIEW&DocID=765

Here is an excerpt:

as Ruth Malan has pointed out, this is erroneous:

... but to indicate that the code is the design language and it is the full (and most accurate) expression of the design misses key points. For example, it misses the "negative space" (things we don't do) directed by the design. It misses the notion that design is an abstraction or conception, and not just any conception -- the design is conceived just-so*, and there is a premise (or a conjoint set) that links intent (or aspiration or purpose) with the particular form the design takes, the organization, the elements, their relationships, their articulation or interaction points, their collaborative interactions, and more. The code contains neither the abstraction** nor the premise. Sure, we want the code to speak to the design, to realize the design and to imply and signify and convey the design as best the code can. And if we create the design in the process of writing the code, simultaneously thinking about design issues and code detail, the point still holds -- we want the code to be as expressive of the design as we can reasonably make it. But both the code and informal tribal memory are going to be missing bits, so it is good to write and draw the design as design out. Or at least the architecture -- the strategically and structurally significant bits. To draw out the relationship of the system to its various contexts, the organization of architectural abstractions (or elements) and their interrelationships and the key mechanisms -- with diagrams and descriptions -- and explicating the reasoning that drove those design choices (and eliminated others). * When I say "just so" I don't by any means mean all at once, but rather that the conception is particular. It is a set of choices (sometimes explicitly reasoned, sometimes more intuitively and implicitly or subconsciously arrived at) that we either can defend or need to try out. We apply insights from experience and knowledge that has been distilled over many experiences, and reason our way to the design approach. And then we test it. Of course. ** Abstractions, yes. Abstractions indicated by the design. But not the design abstraction that contains little of what is in code statements but much of what is in code relationships and form, and in what is not in the code, what is specifically, designedly, not done.

Simon Brown, in his July 2012 Skills Matter presentation, "The code doesn't tell the whole story", listed several attributes of a system that code is generally insufficient to document"

The "big picture" context of the system
Quality of service requirements significant to the architecture
Architecturally significant constraints on the design
Guiding principles of the design
The physical environment (infrastructure) the system will operate in
Deployment locations of the code components
Operational aspects (monitoring, management, security, disaster recovery)
Security

In short, the code the conveys the 'what' but not the 'why' (arguably the more important aspect). It defines 'what is' but is silent regarding 'what should be', 'how fast', etc. We cannot readily infer from the code the physical layout of the system nor its operating environment.

And yet, while the code is the truth, it is not the whole truth . @estherschindler @chasrmartin
— Grady Booch (@Grady_Booch) August 7, 2013

dhh1128 / intent

Make sure all the "negative space" aspects of design are communicable in intent #55