Demonstrations

The actual, true to life, observable behavior of a technology or system.

Specifications

The documentation or proposal of how a technology or system should behave. Can be a prescription created before hand or a description created after the fact; or a mixture of both.

Demonstrations amplify Specifications

Improving specs results in additive gains.

Improving operating deliverables results in multiplicative gains.

Examples

BigCorp

Everything must be described to the most minute detail and approved by comittee before implementation. On paper, BigCorp's technology is not just impressive, but downright magical.

But asking those actually using BigCorp's products yields some different adjectives.

SmallCorp

Being too busy actually building great tech; SmallCorp finds no time to write any documentation. If the users only knew about some of these features they would be over the moon with how well they work.

However, aside from those who made them, no one knows about these wonderful things. How could they when nothing will tell them?

SilverCorp

SilverCorp does not have much documentation. But the little used focuses on overarching ideas and how to get started experimenting with their tech.

They encourage experimentation with the live system in sandboxed environments to allow guided learning in the specifics each user needs.

Their documentation rarely goes out of date because it never over-described their technology or details subject to frequent change.

Take-aways

Having too little specification makes communication more difficult. View it as a broadcast from the past to intercept questions in the present.

Having too much specification risks discrepancies between reality and spec. Sometimes misinformation is worse than no information.

Make it easy to experiment with the real implementation. Being able to quickly run through a scenario the user is questioning provides a better answer than a hundred pages of documentation.

So:

1. Keep specifications brief and high-level
2. Prioritize making real-world experiments easy (aka Demonstrations)