Developer

Application Design: Writing design documents that cannot be stolen

Explaining the architectural design of your application solution to customers is a fine art. Write your design documents with an eye toward protecting your competitive advantage. Express your architectural solution without revealing the details.


Of course, design documents are not literally stolen. It is not as if they are removed from our hard drives by hackers who have penetrated our systems. However, as IT consultants, our competitors will often take advantage of the hard work and thought that we put into the design document.

In today's environment of bidding on the requirements and design phases of a project separate from the construction phases, we often find that the work that we put into our design documents is used by competitors who have invested little or no time or effort in understanding a problem until an RFP hits the street. They then review the documentation that we have created for the benefit of the client and build upon it.

In this article, you will learn how to deliver value to your client in developing a design document—without compromising your ability to be competitive.

The pain of estimating
One of the first things you must realize when looking at how your competitors might use your design documents is that each step of the process of estimating a project is painful. I have never met anyone who enjoys the process of estimating or who can develop a reasonably accurate estimate. For most people, the process of estimating the cost of a project is one of the most painful things they will do in the project lifecycle.

Whether it is a lack of information or the knowledge that your estimate is not likely to be close to what the actual numbers are—no matter how hard you try—very few people are neutral on the topic of estimating. The resistance to estimating or the fear of being wrong has prevented many consultants from ever drafting a proposal.

As you are putting together your design documents, consider that you do not want the estimating process to be transparent for your competitors. You do not want to help your competitors do their estimating because you are creating more unwanted competition for yourself.

Fundamental understanding
During the development of a design document, you will acquire a fundamental understanding of your client's problem. For each stage of the project, you will be formulating ideas for possible solutions. The analysis encompasses the details of the problem, as well the solution. This is one of the factors you can use in evaluating design decisions.

This understanding of the potential implementation is not absolute, unlike, for example, the lines of code written into a computer; however, you develop a feel for how that particular part of the solution will be solved and how difficult it will be. The more detailed the understanding, the more accurate the estimate you can generate.

This fundamental understanding is what your competitors need in order to estimate the project. They need to understand how each requirement will be implemented and how difficult that implementation will be. Without this fundamental understanding of how to solve the problem, they will be incapable of coming up with even a rough estimate.

Of course, they can have someone on staff regenerate the vision for your solution, but this requires time. If you have been engaged on a requirements and high-level design phase, then you may have anywhere from a few days to several months to develop all of the small components of what the solution will look like when implemented.

A fundamental understanding of your client's issues and the difficulty of the solutions is your advantage against your competitors when bidding on the construction phase of a project. It is not something that you want to accidentally give away in your design documents.

Customers want architecture, not detailed design
By and large, the goal of a client in receiving a design document is to understand the architecture well enough to plan the infrastructure and be comfortable with the plausibility of your idea. He or she does not necessarily care about the individual components.

However, if you look at the design documents that most consulting organizations create, they are filled with detailed solutions to the problem. Although it is natural—essentially the design is a blueprint for how the solution will be built—this is not what clients are looking for in most cases. They do not care how the solution will be built at a micro level. They just need to understand the overall structure of the solution.

You can describe in a design document what a particular component will need to do without explaining the internal workings. A good example is a sorting algorithm. You can specify in a design document that a list of items must be sorted using an efficient sort routine. This satisfies the need for a design without specifying whether a bubble sort, quick sort, or other method is the most appropriate way to implement how the list is sorted. How the problem will be solved is an implementation detail that is not necessary in the design document.

For that reason, when putting your design documents together, you should be looking for places where you unnecessarily explain how something will be solved. If the client does not need to know how something will be solved for infrastructure planning, and if it does not add value to the overall understanding of how the solution will fit together, then consider removing it.

Another way to think about this is to consider whether a different technology, algorithm, pattern, etc., could be implemented without changing the basic behavior. If you can answer yes to this question, then you may be writing about an implementation detail—a detail that can help your competitors compete against you.

There is a more direct reason to remove the implementation details. They clutter up a design and make it difficult to read. The more unnecessary details that are included in the design document, the greater its size and the less likely anyone will be willing to read it.

Focus on the what, not the how
If you remove all of the information on how you intend to solve a problem you may be left wondering what will be in the document. The answer is that you should be focusing on what must be done to complete the solution. For instance, in an e-commerce Web site, you will have to handle users forgetting their passwords. That is the "what must be done" part of the design. Obviously, the person must receive some sort of verification information via e-mail and return it to the site. As to how that is solved, cryptographically sound tokens, hashes, and the like are not a part of a high-level design. They are details best left to the detailed design or to program specifications.

As another example, if the requirement is that the system must have the ability to secure specific content, you need only describe a security mechanism, which has these requirements. You need not indicate the development of a security system based on GUIDs where all items in the system have a unique GUID that can be assigned to a user or group. The introduction of the "How" (using GUIDs) into a design document is an unnecessary addition of information that does not help the architecture or design. However, it solves your competitors need for a way to solve the problem.

The focus of a design document is on "what is needed" to satisfy the requirements (what the user wants and what the environment requires). Any other information in the design document detracts from its primary purpose.

Never underestimate difficulty
When you watch illusionists, the tricks that they perform for our amusement appear to be impossible. They are magical because we do not understand how they are done. Once the trick is exposed and we know how the illusion was performed, the trick becomes substantially easier. There may be a measure of skill involved in the illusionist's practice; however, instead of being an impossible feat, it becomes merely a matter of the effort necessary to master the skill.

Developing software is very similar in that there are often fantastic things that can be done with relatively simple things, applied in new and unique ways. Those fantastic things may seem impossible to others who do not have the knowledge of how they are done. By exposing how you are going to do some piece of a solution you are revealing a little bit of the magic that makes you unique and by doing so you decrease your value.

Keep how you are going to build the components to yourself. Illuminate your vision of what is needed to create the solution to the customer's problems.

Editor's Picks