Software

Building project documentation in a 'tailored extreme' business environment

Ken Hardin describes how he boiled down a client's project into a "tailored extreme" document format. This approach might help you avoid pitfalls of under-documented dev projects.

One of my major clients last year operated in what can be best described as a "tailored extreme" project justification and development culture. This was largely a function of the company's relatively small size (the PM and QA manager was the same person, so you get the idea), and the fact that most of the management team were dot.com boom veterans who had ridden in a few IT rodeos in their day.

The company, particularly the VP of software development, pushed hard on the concept of iterative code releases, and senior managers typically had a role in the functional specification review. However, there were seldom true "extreme" model cross-functional team meetings during the coding process (except for questions on the functional spec, etc.), and actual technical specs were solely the dev shop's turf. Moreover, that veteran senior management team wasn't big on formal project justification -- if a C-type executive wanted to launch a project, it pretty much got launched.

As a consulting business analyst, I would get introduced to a project after it was "approved" and queued up, but I would not have created it nor would I inherit formal business requirement documentation, much less anticipated performance metrics. I was left in what many would consider an under-documented environment -- in fact, several higher-ups tended to get a little irritable at the mention of documentation and thought of it as busy work that just slowed things down.

So, my solution was to work out a "tailored extreme" document that involved very light project justification and business requirement information, but went in a little more detail than a typical functional spec. After some trial and error, this approach seemed to work well for the client; it allowed business managers in the "flat" business culture to have input and clarity on some specific technical points (a Search Engine Marketing specialist could dictate what production Web page text carried the HTML H1 tag, for example), while maintaining the dev team's desire to keep technical specs to themselves. It also created some documentation on the business case side, albeit posthumously, which is always a good thing.

I'll describe how I boiled down the project in this "tailored extreme" document format. This approach worked for this particular client's culture, where veteran business managers wanted to (and largely were qualified to) provide input into general database structure and very fine workflow points. I am not suggesting this approach as a replacement for a healthy, fully documented dev cycle. But for a lot of smaller businesses, there may be a few kernels of wisdom here that can help you avoid pitfalls of under-documented dev projects.

Pseudo-project justification

I can't stress this enough -- I made it a point to include some description of current business processes and the goals of the project in my documentation just to have it on the record, and also as a canary-in-a-coal mine check for my client in case I was able to point out some glaring issue with the thought process that went into queuing up the project. It's not to say that the thought process was endemically flawed -- I just had no visibility into it, yet wanted to document it.

I kept this section to about three pages and made sure to touch on these key issues:

Current business practice: About four paragraphs describing the current business practice, where applicable, and business results. I also worked in a simple Visio process flow diagram -- pictures are always a good idea, and such presentation just makes your document feel more complete. Goals and metrics for the new / modified business practice: Depending on your client's internal culture, this can get kind of prickly. If the client was really into projecting hard success metrics, they would have a hard project justification process in place. But, your document should have some insight into what will make for success. You have no real control over whether a credible post-mortem or review happens, but at least you got something in the documentation.

The key metrics to shoot for -- and the ones you are most likely to be able to glean from an "extreme" culture -- are:

  • Increased time to market
  • Increase in unit production
  • Reduced cost of unit production

Improved quality is a bit trickier, unless you are in a client environment with hard product tolerance and flaw definitions -- in which case the whole context of this post probably is not relevant to how you are working. You can also throw in ephemeral goals like "market position" and "brand extension" -- it's hard to put % and $ in front of those, however.

Risk factors

This can get a little dicey, since real risk factors often lie within areas of the company that may be culturally off limits to you (ah, the life of a freelancer). However, in the context of diligence, some discussion of external factors that might undermine the project need to be documented (three or four paragraphs should do).

Market shifts and some very light competitive analysis are worthwhile. I found that I did a lot more homework here than was evidenced in the final document, looking for that canary in the coal mine, and my own satisfaction that nothing obvious was being overlooked.

Part two

Next week, I'll give you examples of the level of business requirements and technical detail I bumped up into the functional spec aspects of the document.

About

Ken Hardin is a freelance writer and business analyst with more than two decades in technology media and product development. Before founding his own consultancy, Clarity Answers LLC, Ken was a member of the start-up team and an executive with TechRe...

1 comments

Editor's Picks