Pictures are worth 1,000 words, but be sure to put words in them, too. Find out what other tips consultant Ken Hardin offers about using visuals in a project document.
Mock-ups have a sense of finality about them that does not lend itself to the business requirements phase of a project, at least not in an informal "tailored extreme" development atmosphere like the one at the client with which I spent much of last year. As I said in my previous IT Consultant column, I tried to keep the visuals in the business requirements phase of the project -- which with this client was more of a reconstruction/vetting of ideas that were already pretty well baked and approved -- to high-level flowcharts of business processes. Wireframes tend to send the message that the requirements are locked, when in fact these business requirements were primarily fodder for a round of three or four polishing sessions to come up with a functional spec.
Except I didn't call the document a spec -- I called the finished product a functional description. Semantics, I know, but in the end the document format I came up with was not as clinical, shall we say, as a true specification. Remember that I was trying to create a document that everyone from the Dev team to VPs could read and get a pretty solid handle on. I highlight could because not everybody in the cycle is actually going to read the document (welcome to "extreme"). The answer? A ton of very detailed mock-ups with narrative text that references the mock-ups extensively and is embedded in the visuals.
Again, let me note that this client runs an Internet publishing site, so the vast majority of the projects I was contracted on involved a visual production layer -- the most obvious candidates for wireframes. But almost any business process or technical schema (warm up that copy of Visio) can be visually illustrated with a little work. In the cases where the functional needed to lay out a meta data framework, I always tried to include a flowchart as a companion to the spreadsheet where the tagging and functionality were laboriously spelled out. Visuals make for a quick read, and it's difficult for anybody (including VPs) to say they simply didn't see that big red button there in your picture.
A couple of notes about using visuals, at least from my experience:Create wireframes, not color mock-ups, unless design aesthetic is not an issue in your project.
Again, this speaks to the sense of finality that pictures impart to documentation. I can't count the number of times I've done extraordinarily rough (i.e., ugly) drafts and sent them off to a designer, just to have them regurgitated back at me in a PSD file with a bevel thrown in here and there. Just because a consultant has design tools on his laptop doesn't mean he is a designer -- that's akin to handing me a box of Crayolas and saying, "OK, buddy, Sistine Chapel in two weeks." Doing simple line drawings (being an old newspaper hack, I keep an outdated copy of Adobe InDesign handy, but any number of freeware tools will work) sends the message that actual look-and-feel remains to be determined by somebody who is good at that kind of thing.
If you are quickly ordering up a couple of new controls on an input form, go ahead and do a screen grab (I really like DuckCapture) and chop it up to create your visual. As always, the trick to good documentation is creating just enough documentation.Annotated PDFs are manna.
Pictures are great. Pictures with words built into them are what you need. Using any common PDF reader, you can add bubble notes to your mock-ups to spell out details such as:
- Data field to populate area
- Action prescribed on user interaction
- Failover behaviors
The list goes on and on. Basically, I found myself porting 40 percent or so of my narrative text into PDF annotations, and it's probably the single-best trick I employed while developing my documentation technique. Remember, when you include a bunch of pictures in your functional description, many folks will tend to not read your narrative. So, put as much info as you can in your pics.You can't just mail a bunch of PDFs, no matter how elegantly they are annotated, and call it documentation. As I mentioned earlier, my functional descriptions would also include an easy-to-read breakdown (no deeper than four layers) and spreadsheets to detail certain data structures. "Certain" isn't really all that discrete, I know, but the reality in "extreme" business cultures -- at least with this client -- is that business managers can get to be pretty technical, at least in their fields of specialty.
It was up to me to decipher what nuts-and-bolts area of a project, such as CMS tagging, the business wanted to spell out to the Dev team, and what areas were considered wholly Dev's domain. Certainly, my "functional" would never attempt to spell out an exact DBMS release or specific technical security measures -- that was left to Dev in their technical spec process, which was largely invisible to the rest of the company. But in a company founded by direct marketers, the LOBs are going to have some say in one-to-many relationships and the like.
All in all, I think the approach to documentation I developed worked well for my client. At least I know the documents ended up in binders that the Dev team noted out and then built the project. And I never got busted on a glaring issue that simply was not addressed or communicated in the process. And that's pretty good news to a consultant.