Once upon a Design

Designing software, planning a project, or figuring out how to test complicated code can be a messy process. At times, you need to tidy things up and present your ideas to others. Francis Galton, a nineteenth-century geneticist, remarked, “It often happens that after being hard at work, and having arrived at results that are perfectly clear and satisfactory to myself, when I try to express them… I feel that I must begin by putting myself upon quite another intellectual plane. I have to translate my thoughts into a language that does not run very evenly with them.” Similarly, if you want to effectively communicate your ideas, you need to translate them into compelling stories.

Identify Your Storyline
Before launching into a detailed presentation of your design, consider what you want to accomplish. What do you want to communicate? What’s essential? What’s less important? Perhaps you want to describe key collaborations between system components. Maybe you want to explain key aspects of your design to newcomers—the major subsystems, their responsibilities, and their patterns of interaction. Perhaps you want to introduce some central software objects and put them through their paces. Or maybe you want to describe how your design supports core use cases; and once people get the gist of these, you want to explain how your design handles exceptional situations. Perhaps you want to justify why you made certain decisions and get critical feedback.

If your story is comprehensive, there will be many things to say. Often, even a simple story has several key points. To start, list everything you want to discuss, whether it is big or small or it overlaps with something already on your list. List things you want to exclude, too.

Let’s say you are designing a function that allows a bank account holder to make automatic payments from his account. Here are some key points about the design story you might want to cover:

• describe how major domain objects respond to a request to make a payment from a customer’s account to a recognized vendor
• use a sequence diagram, but keep it simple
• point out calls to the backend banking system that could be bottlenecks
• start with a well-formed request (ignore UI details)
• relate the diagram to a “Make a Payment” use case (for which there are three alternatives)

Don’t worry about how to organize your story or the items on your list until you have a large part of your story down. Even if your story is brief, you won’t know the best way to present it until you’ve got the content in place and understand what your listeners or readers need to learn.

Understand Your Audience
If you are presenting your design to people just like you, consider yourself lucky. However, often your audience’s interests and backgrounds differ. Some may know a lot and don’t want to be bothered by hearing, yet again, things they already know. Others may need to understand design fundamentals before they can appreciate details. Some may want to know why you made the choices you did. They want to ask probing questions. After all, how can they write comprehensive tests if they don’t know where the complexities lie? Still others may want only the punch line—what you ended up with—and don’t want to hear about how you made the choices you did.

It’s tough to please a diverse audience. You can’t develop one story that will hold everyone’s attention. You may even need to write several versions of the same story. More likely, you’ll pick one intriguing path through all the many ways you could explain your design.