Last week I began a discussion of a “tailored extreme” approach to project documentation I developed while working for a client who was not big on project documentation or a lot of cross-team meetings once development began. Part of the process — jotting in a few pages of business goals and metrics — was almost entirely CYA in terms of my perspective. Those things really needed to be in writing somewhere I could see them, even though they weren’t being employed in what could be considered a formal project justification process. That had already happened in the company’s very informal culture.

The next phase of the project, or at least of my documentation, was to develop a business requirements framework. Occasionally, I would inherit a bulleted list of ideas or requirements; other times, the requirements would be trapped inside the head of managers who had approved the project as a “go.”

At this point, allow me to re-emphasize — these were dot.com boom veterans who had very clear ideas about what they wanted for their business, a pretty large-scale Internet publishing site. The issue was not that there was no thought going into product decisions or design, just that these ideas weren’t being documented and, as such, sometimes were not clearly communicated all the way down the project food chain. This is the point of documentation.

However, there was no point in pretending that I was entering the business requirements phase of a project in full discovery mode. The trick was to either cull or translate the mostly baked notion of the project into a format that I could later flesh out into something that approximated a functional spec.

I ended up with a business requirements outline that was a little down the line from a traditional requirements document. There’s no point in spelling out “the system will allow users to input client mailing addresses” in a business where the VP knows the DB field label where that information will ultimately live. The key to good documentation is having just the right amount of documentation.

What I included in these business requirements varied from project to project. As a rule of thumb, the requirements ended up being about 25 percent of the eventual completed “tailored extreme” spec. I try to keep completed specs to four layers deep (e.g., the specific attributes of a production Web page’s header meta would live in document section 1.2.3.4), and these business requirements outlines would never get deeper than level 1.2.

Even so, they ended up being quite detailed, at least by business requirement standards. Since in many cases the users knew what type of control or interface they wanted, it made perfect sense to go ahead and include that in the business requirements. After all:

  • a) These documents are always up for discussion and can be changed with feedback from any group, including Dev, and
  • b) Sometimes Dev codes what it deems best anyway (“extreme”), which of course can be a hit or miss. It’s always good to have a record.

I tried to include business process flowcharts (which are just golden in almost any context), but refrained from including mock-ups of various interfaces — this despite almost always having done extensive whiteboarding with my line-of-business contacts prior to submitting the requirements for review. My reasoning was that everybody in the process needs to feel invested, and the folks in Dev and QA can have an enormous amount to add the front-end design of any project. And (as I’ll discuss next week) mock-ups have a sense of finality to them that you don’t want to be transmitting at the business requirements stage in an “extreme” or “agile” environment.

Since everybody had an idea about a given project before the business requirements documentation began, this phase of the process went pretty quickly — maybe two weeks, and that was working part-time on an initiative. Two reviews were usually all it took to wrap up the scope and direction, and then on to the fun part — describing how things actually work.