Describing the structural, behavioral, or visual aspects of your software solution in a conceptual way, and in the context of your users’ goals, is the job of the specification document — or “spec” for short. When necessary, the context of your organization’s business goals and technical capability are also layered into these documents. In short, a spec always describes the how — but occasionally includes the why.

What makes specs necessary? Artifacts like comps, prototypes and wireframes serve to describe exactly how form and behavior are instanced in the UI. But a spec will serve to describe the rationale, concepts, and patterns that inform each of these instances. If wireframes predict the weather, specs describe the climate.

Can you just wing it? For large and complex software solutions, you cannot afford to not be explicit in such matters. Leading the user to believe one thing about how your solution is structured or behaves in one case, only to have that belief confounded in another, is UX poison.

What are the qualities of an effective spec?

Specifications, like wireframes are usually internal documents, intended to be consumed by colleagues on your team. And typically your team won’t care what these documents look like as long as they get the message across. Also, the relevance of such documents is often very short-lived.

So I apply a very pragmatic criteria to specs I author: If it was appropriately descriptive, clear, thorough, and delivered in time to be useful, it did its job.

Occasionally, specs must be presented to powerful stakeholders and even potential customers. In such cases, the beauty of the actual document itself may be a factor.

In all other cases, however, as Jeff Gothelf has written:

“Putting in [high levels] of polish and effort into the early stage artifacts — wireframes, sitemaps, and workflow diagrams — is a waste of time.”

Strategy Report
This 2013 spec I authored captures a solution’s root concept and how it should get expressed in the UI.