The primary deliverables of our user experience team here at Savo, as you might well imagine, are design specifications – documents that detail how a new feature will appear and behave. Since these documents are pretty much our raison d’être, we recently decided to examine and optimize how we create them. We had two main goals with this:
1. Make sure that the specs we produce are as valuable as possible to all the people who read them.
2. Make sure that we can produce specs as quickly and easily as possible.
On the one hand, we wanted to deliver content that comprehensively suited each of our consumers’ needs. And we also wanted to make the logistics of producing that content as smooth as possible for ourselves. So how did we go about solving this problem?
First, we looked at the different consumers of our documentation and tried to understand their different perspectives on the design spec.
-The product team looked at the documentation and began to imagine how the features would work together with the existing app. They needed to be able to see a high-level view.
-The developers looked at the documentation and began to imagine how the features would be implemented. For them, it was important to draw attention to places where we wanted to change existing behavior.
-The visual designers needed to know which graphic elements of our design were important to keep intact and which were just suggestions.
-The QA team looked at the documentation and began to think how they would test each screen. They needed to know the exact parameters of how the screens should behave.
-The solution architects looked at the documentation and started to think about how the feature would mesh with existing implementations. They needed to know which parts of the design were static and which would be customizable.
Then we looked at our existing process and tools and tried to determine how documentation should fit into that. We used to produce documents by hand in Word, which was both restricting in layout and quite time-consuming, so our first thought was to leverage our prototyping software (we do both mockups and prototypes in Axure) and its document-generation feature. However, the output was still in Word and it still required quite a bit of post-hoc massaging to look how we wanted.
Since we ruled out automation and we really wanted a lot of flexibility, we decided to go with a standalone tool — Adobe InDesign and the EightShapes Unify document templates. Switching from Word to a proper page layout tool and the Unify framework really kicked up the amount of freedom we had to present concepts. It did require a little more up-front work to become expert at InDesign and to customize the template the way we wanted, but that investment quickly started to pay dividends.
For one thing, Unify’s landscape layout with small type allows a lot of information to be placed on a single page. And the information can be visual or verbal, depending on whether we need a big picture of a screen with callouts/highlights, or a lot of well-organized text to describe behaviors in detail. With this flexibility, we were able to take another look at our stakeholder groups and deliver pages that would be specifically targeted to their needs:
-In general, we tried to include “birds-eye” views of an entire screen (more targeted at the product team), then break up the screen with detailed enlargements on subsequent pages (aimed more at the dev/QA teams).
-For the visual designers, we augment our typical callouts by showing side-by-side comparisons of current styles with our proposed styles. We also include one page dedicated to explaining any new iconography that needs to be developed.
-For the solution architects, we include a page that details the client-customizable elements, with small cutouts so they can see the element in context.
So now, having gone through this process redesign myself, I’d love to hear some stories from other designers: How do you approach design documentation? What tools do you use? And, most importantly, do you have any great InDesign tips?
Well done! Imagine that – audience-specific documentation design considerations. Can you talk more about some of your challenges and/or delightful surprises in using the system? And how did this tool & template set stack up against others that you considered?
Hey Nathan – thanks for the feedback, and thanks for your team’s time and effort in creating a great template set!
Maybe I didn’t do enough research, but when I was looking online I really didn’t find any templates in the class of Unify. So we had Word-by-hand (old method) vs. Axure automated Word vs. ID-by-hand vs. ID/Unify. The “by-hand” methods got thrown out because we wanted our work to look uniform, no matter who on the team was primarily writing it (and we all have slightly different conventions no matter how hard we try to eliminate them!)
So then when we had narrowed the decision to Axure automatic generation vs ID/Unify, we went through the documentation process, trying out each method on a small feature. I think what really won us over was:
a) the workflow of keeping screenshots linked into the document, so when we update a design in Axure, all we have to do is quickly re-take the screen cap and save it over the old one. With Axure, we had to do a full regen of the documentation each time, and then re-apply our Word tweaks.
b) the library of styles/pages/objects in Unify is really nice. It’s been fairly easy to customize, even for we relative InDesign novices, and we now find ourselves saying “hey, I think we can use the templates for that” when we’re making random one-off documents.
The main challenge I think has been the learning curve of ID paired with learning which Unify styles we want to use and how they inherit… autonumbering and tables were the pain points out of the box, but I think we got the kinks ironed out as we learned more about InDesign.