How Analysts Can Show Craftsmanship in Their Work

Recently we hired a woodworking friend of ours, Ray, to do some cabinetry and finish carpentry for us. Ray has a reputation of being a “true craftsman,” and we felt lucky he was available.

On his last day we were sitting together, admiring the result of all his hard work, and Ray got up and walked over to a particular spot, saying, “This is bothering me. It’s not right.” This perceived flaw could be seen from only one angle and only if you were looking for it, so we weren’t concerned about it. We thought Ray was just being a perfectionist.

I’ve been thinking about software craftsmanship and what makes one a “craftsman.” Software craftsmanship has been a popular topic since Watts Humphrey proposed the Personal Software Process in 1996, followed by the Team Software Model. Books have been written about it, conferences have convened around it, and there is even a Manifesto for Software Craftsmanship.

But everything I have read about craftsmanship seems to have to do with the quality of the code and good coding practices: the realm of programmers. Surely, I thought, programmers don’t have a monopoly on craftsmanship.

I’ve been mulling over how the concept of craftsmanship is relevant to analysts—business analysts, quality analysts, testing analysts, or process analysts. Being curious about how concepts are applied in other disciplines, I asked Ray how he defines “craftsmanship.” He looked at me as if I had two heads. I pointed to the work he had done and pressed him to articulate what he was thinking. He said, “A craftsman anticipates and prevents your problems before you know you are going to have them. The ability to do this comes from experience and accumulated knowledge.”

So, how might craftsmanship be manifested in analysis work? Over the last couple of months, I’ve focused on the users of the interim software work products we create and captured some practices analysts can employ to demonstrate craftsmanship to their customers.

Do You Know What I Mean?

Define acronyms and unfamiliar terms at the beginning of the document. It is common practice for the writer to define an acronym the first time it is used, but a reader might not start reading at the beginning. Why put the burden of finding your first explanation on the reader? Using an “Acronyms and Definitions” section also enables collaborative review.

Is Anything Ever Final?

Have you heard the expression “The only constant is change”? When I see the word “final” on a document, I wonder whether the author is in denial about change or is perhaps exhibiting wishful thinking. I can think of only a few situations when something is truly final, so stop using the word “final” in file names. Because where can you go from there? Final Final? Absolute Final? I Really Mean It This Time Final? Learn how to baseline and version and anticipate change. Oh, and put the version number and date in the footer, because . . .

Some People Like Hard Copies

Some people will print your work product to post on the wall or to read and annotate outside the office. Some people just want to avoid scrolling and prefer the physical act of turning pages.

It is easy to anticipate this desire and format a document for printing before sharing it. Think about orientation, page breaks, headers, footers, version or date, etc., before distributing the document. If you don’t, you are transferring the burden to your customers, and each person who prefers a hard copy pays the formatting price. I realized this when I received numerous files from a creator who didn’t anticipate my needs. I formatted the work product to print and post, and soon others were asking me if they could just make a copy of mine. When I mentioned this to the creator, he said he didn’t bother because he didn’t think anyone would print it; the client was making an effort to be “green” and discouraging gratuitous printing.

Setting your work product up for printing to begin with doesn’t mean it has to be printed, but it will it save your customers time and effort.

A Picture Really Is Worth a Thousand Words

The users of your work products are likely a mix of left-brained and right-brained people; that is, some prefer words and some prefer pictures. When you provide both, you can use one to validate the other, ensuring completeness and accuracy before distributing. When you receive a text description of something, try to draw it. This is a great way to flush out omissions or conflicts.

Once, when configuring workflow status in an ALM system, the project manager shared a list of status transitions he had drafted and asked for my opinion. I looked at it and said I’d need to sketch out a status transition diagram before I could answer. He assured me I didn’t need to go to all that trouble, but I knew I did. And sketching it enabled us to find an omission that wasn’t clear from simply reading the text.

Is That Color Just Pretty, or Does It Have Significance?

If you use colored text or shading, include a legend or explanation about what the colors mean. If they don’t have meaning and you are using them for readability (e.g., shading alternate rows), say so. Otherwise, your customers could waste a lot of time trying to infer why you used an aqua fill here and a lavender fill there. Anticipate this, and if you are using color simply aesthetically, just say “Colors and fill have no meaning.”

Another approach to color is to use it mnemonically, such as using fuschia to mean “future” or orange to mean “optional.” If you are working with a sequence, going in rainbow order and using red, orange, yellow, green, blue, indigo, and violet can be helpful.

Before using color, find out if the users of your products have any visual impairments or restrictions about color printing, or whether there are strong cultural associations with the colors you plan to use.

Does X Mean Yes or No?

Have you ever looked at a grid, matrix, or table of columns and rows and seen an X in a cell and wondered whether the X meant yes or no? Does an X in a cell indicate inclusion or an exception? Simply using Y to indicate yes and N to indicate no removes the guesswork and potential miscommunication. If you are in the habit of using X, you can do that, then do a search and replace the X with a Y or an N.

We focus a lot on the users of the ultimate product; thinking about the users of our interim work products and making their problems ours before they even know they have them can demonstrate our craftsmanship as analysts.

Ray would be proud!