The Communication Studio

Specifications

The Design Specification document establishes how we organize and present that information in the User Interface.

It is often the common point of reference for sign-off by stakeholders - and provides guidelines and continuity throughout the process.

Identify the "HOW"

When viewing the Design Spec, business stakeholders have one agenda, the technical team another. The biz guys are looking at business requirements and workflow, the tecchies are looking at data structures and code objects.  A Design Spec (often called a "Functional Spec" by the tech team) should provide the common ground for both worldviews:

  • It is a set of screen-based visual images + behaviors
  • that reflects the goals, tasks and workflows that have been described by the business side
  • as well as the constraints and requirements of the technical environment

The trick is to create a document that is comprehensive, informative and readable.

Push active design to the forefront.

  Most decision makers see the "vision thing" of what we're creating as a dance of screens, not as an abstracted Visio diagram (just watch their eyes glaze over).  The sooner the design is turned into clickable HTML Wireframe, the better. I generally try to "annotate" my HTML prototypes with funcspec info, so that the model is itself a living document, but a good ole paper document has its advantages.

Why bother?

You know the story: The development team has already produced 50,000 lines of code - and now they call in an design person to "make it usable". Often one of the first things I do is to capture "what it is" in a Functional Spec (which never got written in the first place). It's scary how many products move forward without capturing the basics...

The "Design Specification" (I've also heard it referred to as a Conceptual Design doc, UI Spec, Interface Design, etc.) is the high-level overview that provides context and common ground for everyone on the team. Stylistically, it's the "illustrated novel" or "manga" version of The Vision: It offers screenshots, lotsa visuals, the essential functional points, and a lean Cliff-notes summary of the story. Just the sort of thing that attention-deficient stakeholders might be willing to scan for a couple of minutes. Combine it with a shallow-working HTML model, and you might actually convince them.

If your working environment doesn't clearly define the document role, you might want to evangelize. The Design Spec document is strategically influential. If you own it, you swing some heft in the process. Even those who huff & puff about RAD ("We don't need no steenking documentation") will probably still embrace this "documentation lite."

Stylistically, it's the "illustrated novel" or "manga" version of  The Vision:  It offers screenshots, lotsa visuals, the essential functional points, and a lean Cliff-notes summary of the story.  Just the sort of thing that attention-deficient stakeholders might be willing to scan for a couple of minutes. Combine it with a shallow-working HTML model, and you might actually convince them.

Disclaimer: I've been a Tech Writer and Documentation Manager. I believe that documentation is underappreciated within the process, often poorly executed (esp. in terms of "nobody wants to wade through it"), and absolutely critical to our success. As the "designated communicators" in the development environment, it's ultimately our responsibility to advocate it. I often try to be a "liaison" among the various team cultures - collecting, interpreting, translating, and serving info up as appropriately as I can.

I often describe myself as "a Business Analyst with design talent"

Project Overview

This short "one page story" is the accessible, descriptive overview that should accompany any well-conceived discussion.  In my own writing, I append such an overview at the head of every document produced for the project: It is the context for all that follows:

Business Case

Describe (at a high level) "why we need it" - the purpose and goals . from the perspective of the client and the enterprise. It is the highest level of description and lays the justification for the business requirements. This may include:

  • Perquisites and dependencies on previous products
  • History
  • Legacy Issues
  • Target audience
  • Anticipated impact
  • Market Forces
  • Competition
  • Perceived customer motivation

Actors & Roles

Identify (at a high level) who can do what . We have to know who we're talking about and how they work. This is particularly critical to our ability to design a "customer-centric" product.

  • Roles
  • Tasks
  • Use Cases
  • Permissions

 

Goals & Tasks

Identify (at a high level) "what you need to be able to do" . a practical description of what tasks you need to accomplish in the business requirements.

Assumptions & Risk

Identify underlying "givens", s.a. the relationship to existing software. Identify any technical risks associated with the development of new capabilities.

Product Perspective

Describe the relationship of the system being developed to other related system products or components, including a general description of the technical interfaces. This may include:

  • Hardware interface requirements (i.e. Technical perspective)
  • User interface requirements (i.e. Design perspective)
  • Marketing or client-specific information which helps to put the product capabilities into perspective (i.e. Business Perspective)

The trick is to create a document that someone actually wants to read.

Workflow Map

You can create or edit Executions and add Purchase Contracts and Sales Contracts to their affiliated Loadings. Every Execution consists of one or more Loadings. Every Loading consists of one or more Purchase Contracts and one or more Sales Contracts.

The Overview captures the basic business goals and functional outline concisely. The Workflow is a high-level visual "snapshot" of the Tasks.


Stakeholders & Actors

The Execution Staff can view, create and edit Execution records and their affiliated Loadings. They can Settle Loadings. They cannot manage Overfills and Underfills.

Traders and Trade Admins can view Executions and Loadings. They cannot Settle Loadings. They can manage Overfills and Underfills.

Accountants can view Executions and Loadings. They cannot Settle Loadings. They cannot manage Overfills and Underfills.

Task Function Use Case Permission
Search & Select Search & select Executions and Loadings UC14 Execution Staff, Trader, Trade Admin, Accountant
Create Execution Create new record UC11 Execution Staff
Edit Execution Edit existing record UC12 Execution Staff
Create Loading Add Purchase Contracts, Add Sales Contracts UC15 Execution Staff
Edit Loading Add Purchase Contracts, Add Sales Contracts UC16 Execution Staff
View Execution / Loading Print Loading, Settle Loading UC13, UC17 Execution Staff, Trader, Trade Admin, Accountant
Manage Overfill Contract overfilled UC19 Trader, Trade Admin
Manage Underfill Contract underfilled UC20 Trader, Trade Admin

 

We know which Actors have Permission to perform a Task. Tasks are generally identified in Business Case and Business Requirements documents. Every primary Function is captured as a Use Case ("UC") , which is described in a separate document.


Screenshot

Execution Staff can create and edit (Traders, Trade Admins and Accountants have View-Only permission).

Clickable items in the Search Results table go to either Edit or View pages, depending on your permissioning.

The screenshot provides a visual reality check for style, layout, understandability, appropriateness and conformance to presentation standards.

The sooner it's HTML, the better.

Page Elements & Controls

Item Type Action Bizrule
Search Results Table table Populated by system:
Execution ID, Vessel Name, Loading ID, Loading Type, Status, Profit Center, Commodity Group, B/L Date, Loaded Quantity, UOM
BR155
Execution ID link Go to Edit Execution page. BR127
Loading ID link Go to Edit Loading page. BR128
Add+ link Go to Add Loading page. BR148
Settle link Begin Settlement process. BR160
Create New Execution button Go to Create Execution page BR156

 

Every Functional (i.e. clickable) Item is identified by Type and described by Action. We identify the appropriate, underlying Business Rule ("BR") and describe it in a separate document.

View the case study in my portfolio: Bunge Global Markets

How does it work?

What are the boundaries of a Functional Specification? Seems to differ from team to team. Often it's a huge, unwieldy all-of-the-above doc that's hard to create, maneuver or manage. As such, it's inappropriate for a small-team Agile environment. Plus - nobody wants to read it. And, even tho it *should* exist before work begins, of course it never does.

At the high level:

  • Break it out into manageable chunks
  • Each with an appropriate author and voice
  • Robustly cross-referenced (to avoid redundancy: one-source)

Product Snapshot: Overview (Product Owner)

Business Requirements: What, not How (Business Analyst)

Technical Specifications : Constraints, Data (Development)

Design Specifications : Presentation, Behavior (UX)

Craft additional detail as you move into the project (scalable)

Collaborate with other team players, s.a QA, on relevant issues

Net/Net: Documentation is the manifestation of Process. It's a skillset in its own right - the sort of thing that UX should advocate. After all, docs are useful only to the extent that they are usable.