Thursday, May 23, 2013

Traceability Helps Business and Development Understand Each Other

Traceability came up several times in a recent tech-writing seminar I led, although we never called it traceability. The problem under discussion was communication across disciplines, or how to get the people on the Business side and the people on the Development side to understand each other.

The situation

Business Systems Analysts (BSAs) are often in the middle between Business and Development and charged with creating a business requirements doc (BRD) reflecting Business interests and a functional spec (FS) that Development can use to turn the B requirements into D functions on a web site or in software. Traceability is the BSA's best friend.

According to "Never 'Without a trace': Practical advice on implementing traceability," a piece on IBM's developerWorks site, traceability is "...the ability to trace a project element to other related project elements, especially those related to requirements." In other words, traceability shows relationships among functions and requirements (reqs), making it easier for readers with different backgrounds to understand how reqs map to features.

In your undergraduate days, if you were in a non-technical major, you learned about the importance of audience analysis, or the process of figuring out how much readers already understand about your topic so you can decide how much to spell out and how much to imply. Well, the principle of traceability says, just spell it out because audiences are so far apart that when it comes to common knowledge there's little common ground to stand on. Traceability provides common ground.

Traceability comes from information BSAs include in the functional spec that has the specific purpose of validating and verifying requirements and functions and addressing the basic questions--according to author Thomas Behrens--"Are we building the right product and are we building the product right?" Bs care about the first half of that question; Ds care about the second.

What does traceability look like?

It looks like words or grids/tables/illustrations that show a specific req, feature, and use case in relationship to each other. Here's an example.

When you show relationships, it's easier to measure specific impacts on process. Who is the source of most changes? Who provides the clearest, least ambiguous requirements? Whose are vague? Who's reqs are implemented? Whose are not?

Including traceability in your information-design process provides a way to measure your productivity as technical writers and the value added to the project by the tasks you perform. Behrens cites three specific benefits:

Traceability enables you to measure

1. the percentage of requirements actually implemented
2. the percentage of reqs that test successfully
3. the number of tests that have to be rerun due to changes

No doubt dozens of additional metrics can be derived from traceability efforts, and the more you measure, the more concrete, targeted ways you can improve the information-development process.

Monday, May 13, 2013

GPACW13 at the University of Minnesota

The Department of Writing Studies at the University of Minnesota is hosting the 17th annual Great Plains Alliance for Computers and Writing, Friday, November 8, 2013 at the Continuing Education Conference Center on St. Paul campus. The CFP is here:
We look forward to seeing you.