Design Documentation

Alice Toth, Thursday, July 30, 2009 @ 5:31 am

photo credit: theD40kid

A few years ago, I worked on a team that was trying to move the business side away from the waterfall method into more of an agile approach so there wouldn’t be such a disconnect between design and development. Since there was no blueprint on how design could be done in an agile fashion, resistance was very high. One of the major sticking points, however, was in documenting requirements. The business side controlled the process which meant no one could see or review the requirements until they were released by the analyst. In a world view of us vs. them, collaboration was not very high on their list.

Collaboration, however, is high on the list for agile development. So, how to resolve this conundrum and begin to merge the two teams. The eventual solution was to use a wiki for documentation and to note when requirements were still in draft form. This process raised the comfort level of the analysts that they wouldn’t be unduly criticized before they’d finished writing, but still allowed for review and questions by others. It took a number of cycles before the analysts were comfortable with having their drafts visible by all, but eventually it happened.

The next hurdle to overcome was the format for the wiki pages. Luckily, the analysts were accustomed to using a Word template and, therefore, were in agreement that a standard template needed to be used. However, a one-to-one translation of the Word template to the wiki just did not work. For example, was a title page really necessary (yes, they actually reproduced this as a wiki page). No? gone. What about a notation of who revised the document when? The wiki tracked changes so explicitly stating this was nothing more than busy work. Table of contents? No longer needed as the content could quickly be scanned since requirements were now for an iteration and not a release. And so on and so forth.

What works in a paper world may not translate well into a collaborative, digital world. However, changing a process doesn’t happen overnight. Your best approach is to take an iterative approach: ask the developers what they read and what they ignore on the current format — then ask the same of the business stakeholders and anyone else on the requirements reading list. Ask your team members what their workflow is through the parts they actually read, i.e., what they focus on first and so on. Once you get a better understanding of the essential components, take the original template, pare back to the necessities and organize in a manner that best suits your users. After all, just enough documentation works for design as well as development.

Related Services: User Experience Design, Custom Software Development

Related posts:

1. Integrating Design and Agile Development
2. One Way to Organize the Documentation for Wikis and Trackers in Agile
3. Design Thinking
4. Agile Development, Documentation and Bringing Projects back from the Dead
5. Developing Good Wireframes Ahead of Visual Design

Comments (2)

User Experience Design

Comments: 2 so far

• Leave a comment
• Comment feed for this post
• TrackBack URL

1. 

   Good advice, Alice! We’ve been using wikis for documenting requirements for three years now and have found that it works wonderfully for collaboration among the design and dev team, but is still difficult for business contributors to know “where they are” in terms of validating the requirements.

   Since our wiki requirements are highly interlinked, it’s a challenge for validators to follow links, reading requirements, and knowing when they are “done.” They tend to prefer linear, document-based requirements documents.

   Have you found a good balance between these different needs?

   Comment by Steve R, Thursday, August 13, 2009 @ 9:10 am

2. 

   Organizing a wiki can indeed be tricky and I try to minimize interlinking on requirements because it’s too easy to lose your train of thought.

   At Pathfinder, I came up with a requirements template that is contained to one wiki page. We can do this in part because we do agile design and development which means we only write requirements for the features that are to be built in the next iteration. Since we have two-week iterations, features are never these epic stories and the requirements can reside on one page.

   The biggest advantage I’ve seen is that it’s easy for all team members to scroll down to the area that interests them most and then easily scroll to a reference in another section (e.g., design specs referencing a wireframe). When going through various iterations of the requirements template, their feedback was that scrolling a long page isn’t a bother but clicking to a new page is. So, one page it is.

   Comment by Alice Toth, Thursday, August 13, 2009 @ 10:51 am

Leave a comment