In my last post, I discussed the value of design documentation. In this post, I share some practical tips on writing design documentation. The first part outlines general approaches. The second describes customizing annotations in Axure.
Approaches to communication
In my presentation on communicating design, I talk about four types of design documentation:
- Walkthrough presentation with screen-level comments
- Screen shots with call-outs on specific elements
- Screen flow document with call-outs
- UI design specification
These types are not so much about specific formats. Instead, they represent a continuum of communication from least specificity to greatest detail. I blend elements from each as needed to meet the needs of different audiences. As I stated previously, design documentation is about communication, not a document or some tightly prescribed format.
Because the level of detail varies, each approach offers different value to the various audiences. If exhausting detail is not immediately relevant, few things can cure insomnia faster than reading a detailed UI design specification. On the other hand, insufficient detail to guide and support development can cause a project manager to lose sleep. Pick the level of detail appropriate to your audience. If you are serving multiple audiences, consider how you might blend approaches or whether you need multiple approaches tailored to your audiences.
Other project communication also influences the choice of approach. When the designer is likely to be highly engaged and accessible throughout a project and beyond, a less detailed approach may be sufficient. Highly detailed UI design specification is essential if the designer is likely to have low involvement during the development and testing phases. This latter case is especially relevant with widely distributed development teams that may have limited meeting times. As for the long term use that I discussed in my last post, more detail is usually better. Project culture and methodology is also a factor as these set overall expectations for project communications.
Knowing the kind of communication you need to provide and is appropriate to the audience is useful for planning the organization of your design itself. In a prototyping tool like Axure, that can also influence how you organize your prototype and how you set up your annotations.
Customizing annotations in Axure
You capture annotations in two places in Axure: attached to each page and attached to individual widgets. You can customize both.
When you know that you are preparing a walkthrough or screens with call-outs, you likely want to focus on customizing the page notes and you should design your prototype to present states as discrete pages rather than to use many dynamic layers.
Customization of page notes is simply a matter of creating additional page note. Click on the Manage Notes… link. In the Page Notes dialog box displays, click the + icon to create a new page note type.
I like to put system messages such as errors and validations in page notes, as widget level annotations do not easily accommodate multiple errors and validation conditions and messages or page-level validation.
Another useful page type is the screen flow. You can document where a user enters a page, the steps for task completion on the page, and the exit from the page. If you have an extremely linear flow of screens, you can produce what I refer to as a screen flow document this way.
When you generate the specification (I will discuss customizing the generated specification in a future post), you can set Axure to include the page note title in the generated specification. So make the name as meaningful as it needs to be.
To switch between page notes, select the note type using the drop down list in that page panel at the bottom of the Axure screen.
To provide more in-depth detail about the different screen elements, use widget annotations. Widget annotations are also useful if your prototype needs to show complex interactions and relies heavily on dynamic panels. You can customize both the annotation fields and how the fields are organized, called Views.
For most projects, I remove the default fields about project management (Assigned To, Target Release, etc.), as other project documents capture those details. To manage annotation fields, click the Customize Link. In the Customize Fields and Views dialog, you can remove standard fields you do not need by selecting the field name and clicking the X icon.
To add a field, click the Add menu button and pick the type of field to add. If you’re not sure what kind of information you will need capture, Text is generally the most flexible field type, allowing for lengthy entry despite showing a single entry line in the Annotations panel.
What you include will depend on your specific communication needs (pages 10 and 11 in my communicating design presentation list possibilities). Three types of information I usually include on any project are
- Related requirement: Whether numbers from a traditional requirement specification, use case titles, user story names, or other reference, show what requirement a specific control serves can be helpful. I also will reference any user research that supports the control selection.
- Rationale: If I am creating any unusual patterns or complex controls, including my rationale can make it clear what problem I’m trying to solve and why a particular control accomplishes this. If the design needs to be adjusted, this informs that discussion. This information is especially useful to maintenance and future release development teams.
- Behavior: I use this to describe interactions that would be difficult to model in the prototype, that might be overlooked and are critical, or that might have multiple outcomes depending on entry criteria such as a user role.
Once you’ve created your annotations fields, Views allow you to organize them. To create a view, click on the Views button at the top of the Customize Fields and Views dialog. Use the + icon to create a view. You then select your new view and use the Add menu button in the Fields in UI Design panel to add annotation fields to each view.
Views are available in a drop down list in the annotations pane. The value of this option will depend on how much information you are capturing and your preferred way of working. When a lot of custom annotation fields are defined, I use Views to focus on areas and make sure I have defined most critical fields (not all widgets will need all fields). When I’m capturing less detail, I may not use Views at all.
Although I haven’t had a chance to put use Axure this way, I can also see how Views would help manage work in cross-functional teams. If a team is using a shared Axure project, Views could denote one set of fields, say, for the content strategist, another for the visual designer, another for the accessibility specialist, and yet another for the interaction designer.
One final tip is that, while it may be tempting to add a lot of detail, only put in what the audience for the design document will really use. Anything that isn’t absolutely useful is clutter that takes time from other work you need to do and distracts from essential content.
By customizing annotations at the widget and page levels, you can be sure to include all and only the information needed in your design documentation. Even if you are not working in Axure, identifying what you want to capture and at what level of detail also provides a content outline that you can preview with the project team to make sure they have the information they need to implement your UI design. This preliminary planning helps promote trust and communication on the team.
I hope these tips help you as you plan your design documentation.
