Design Documentation

---

Having the design documented is critical in making sure that what is build looks and behaves the way it was intended. I use a combination of visual style guides and behavioral specifications to communicate the design as well as meetings and frequent informal communication to make sure questions are answered as they come up and everybody is in the same boat.

Visual Style Guides

Visual Style Guides communicate the dimensions and visual design of an interface for the developers who can then take the guidelines and build the interface accordingly. Having thoroughly documented design eleviates engineers from having to think about things like layout and typography and enables them to focus on the functional aspects of the product. The style guide should always be accompanied by the graphics that are used in the UI like buttons, corners, logos, etc.

Depending on the structure of the product team, these graphics can be produced by a production designer or by a developer who is familiar with graphic design tools like photoshop or fireworks.

The advantage of the designer creating the graphics is that she is already familiar with the look of the interface and has the files that the graphics can easily be exported from. The advantage of the developer creating the graphics is that she knows exactly what she needs and she also might use naming convention for graphics that the designer would have to learn.

Behavior Specification

As the name indicates, the behavior specification describes a product's behavior. The behavior specification is essentially a list of all the views, panes, and pages of the aplication and all the controls on them with a description of the product's behavior that is evoked if that particular control is triggered by the user.

Standards for Design Documentation

I also establish standards for creating and maintaining design documentation with a focus on documenting design in an agile environment.

The Value of Design Documentation

Detailed design documentation is a considerable amount of work and raises the question: is it worth it? I have come to the conclusion that is is. Design documentation costs time but the lack of design documentation will take up a lot more time spent in clarifying design decision with the developers and in the worst case recoding parts of the UI. It leads to higher quality products and reduced development time and higher morale due to reduced need to re-evaluate and re-code functionality.

As a simple example, it takes a designer less than a minute to specify a 20px margin on a page. The developer then knows to code accordingly so the margin on the screen is 20px. The alternative of not documenting usually results in one of the following scenarios:

1. The developer who is tasked with building the interface decides on a margin himself. There are a lot of considerations in deciding on a margin size that have to do with the overall design, consistency, and cognitive principles that the developer won't likely know since the designer developed the entire system of visual interface design. In all likelyhood the developers choice will be different from what the designer would like to see. (and it shouldn't be the developers responsibility to do this in the first place). At some point the designers will probably notice the discrepancy and point out that the margin needs to be "fixed". Just communicating this fact already takes up more time than specifying it in the first place. Next, the developer is likely frustrated because he already coded that part and doesn't want to re-do it. So there is some discussion about the necessity of re-coding it. By the time the developer actually re-codes it, both, the designer and the developer probably spent more than 1/2 hour on this together. So 30sec vs. 30min? I think design documentation is worth it.

2. The developer is unsure about the intended size of the margin and goes back to the designer to find out. While better than the first case, this still disrupts the designers workflow, and takes up time to communicate something that could have been done in the first place. If it isn't noted somewhere, chances are that the developer is going to ask several times, or, if there are more than one developer working on the UI, every developer is likely to pose the same question and take up both their own, and the designer's time.