Design Documentation

This post was previously on the Pathfinder Software site. Pathfinder Software changed its name to Orthogonal in 2016. Read more.

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: Custom Software Development