Design as Specification for Developers

Being a fully agile team, Effective (and previously Handsome) faces the common challenge of keeping the product specifications for our engineering team well maintained and up-to-date.

On one hand, it’s essential to follow best practices in product development. This includes keeping specs updated, which leads to better team synchronization and overall productivity. On the other hand, since we’re focused on moving forward and innovating, we might not have enough time to keep specifications up-to-date. The larger and more complex a project gets, the less organized specifications tend to become. Often, they end up being stored in different documents, where one document could easily contradict another. Not ideal, right?

A well-known and popular Agile practice to address this complexity is to write executable specs, use auto-generated documentation and document general concepts, but not details. Also, it’s important to keep the documentation and requirements consistent and store them in a place where they’re easy to share, update and use.

Traditionally, the software system description is stored in a Software Requirement Specification (SRS) document. A requirements specification is a set of statements describing:

• what the system must do,
• how it must behave,
• the properties it must exhibit,
• the qualities it must possess,
• and the constraints that the system and its development must satisfy.

We’ve tweaked this model a bit. In our process, we use our team’s visual design deliverables as input documentation and requirements specification for the development processes.

We’re confident in the core ideas conveyed by the visual design artifacts because the designers on the team have already reviewed UI prototypes with key stakeholders and end-users. Together, we extend design deliverables by defining edge cases, different application states, and adding a few annotations for clarification. This allows us to use visual design as specification for development.

Here are some of the guidelines our team follows in order to produce deliverables that helps boost our efficiency:

1. Include user flows in visual design artifacts: show the flow of all possible cross-screen user interactions.

Users scenarios may be displayed in visual design as scenario maps.

2. Include a comprehensive set of all possible screen or element states in the application.

Our team follows the guideline of 9 States of Design:

• Nothing — the component is not initialized;
• Loading — data has been requested from data sources and is loading;
• None — no data has loaded or been added, the component is empty;
• One — there is only one item in a list, or on the screen;
• Some — typical state of a component, it has some data;
• Too many — too many results or data is very big for this component;
• Incorrect — incorrect state after validation, wrong data;
• Correct — correct state after validation;
• Done — operation is finished, Item is selected, etc.

3. Include notes and comments.

Short annotations may describe non-trivial behavior in the design that may be difficult for developers to understand from the set of static screens.

4. Provide dynamic prototypes for animations and transitions.

Sharing dynamic prototypes for interactions and transitions helps us to show duration, speed of transition, and other important attributes directly from the prototype. Most often, we use Principle for this.

5. Add error states.

The real world is not ideal and errors occasionally occur. Our design documents contain different cases to show error states.

1. Not loaded — no internet connection or there is no access to data sources.
2. Data corrupted — required data is missing or data structure is invalid.
3. Unexpected error — internal issue, application failure.
4. Keep the visual design artifacts up-to-date.

Requirements should never be out-of-date. So if anything on the project gets a visual or logic update, we update the design team deliverables.

6. Demonstrate all updates and changes to the team.

All developers should know about updates and work only using final, up-to-date information. A regular cadence of meetings, where designers demonstrate their updates, helps significantly.

This approach has proven to work well on products that have a lot of screens and UI features, as long as the business logic is relatively simple. For more complex products with a lot of business rules on the frontend, we create additional documents describing the requirements and business logic.

Using UI design as a specification for developers helps us keep all needed documentation in one place and updated in a timely manner. Because responsibility for making updates rests with one person — the UI designer — any engineer can easily find the latest version in the repository, review it, ask questions and create awesome products.

While preparing design documents, our design and engineering teams collaborate closely and, together, can achieve amazing results. Great teamwork allows us to accelerate the development process, understand each other more completely, and make successful digital experiences.