{ End Bracket }

Engineers Who Write

Richard Ward

See Richard Ward's "Behind the Code" interview at channel9.msdn.com/Shows/Behind_The_Code.

I was somewhat amused when the MSDN Magazine staff asked me to write a column. There was an initial trepidation, as if engineers were not expected to write and raising such a request was inviting some sort of surly response. This happens more than it probably should, but it indicates a more general issue.

Engineers—and indeed everyone involved in creating software— need to be able to communicate verbally, and that doesn't mean by speaking. Oral communication is great; having a small set of people hashing out details on a whiteboard or over lunch is an invaluable part of completing the design. The rapid interaction allows everyone to bounce ideas around and get immediate feedback. But it is, by its nature, imprecise. The understanding developed during the conversation and the shared context built by the participants rarely extends past the conversation. Only what is written down can be used by people outside the conversation.

Writing down ideas and concepts is essential to the development process. While there are many schools of thought on what constitutes the right level of design for a software product, ultimately some aspects of the design must be written down. And much like the notion that no backup product is good unless you verify its restore abilities, whatever is written down must also be readable by the intended audience. If someone reads the document and can't understand the goals, or worse yet, gets a completely different understanding, then the process has failed.

There are a lot of opinions about what should be used when writing engineering documents. I'm not going to stir up that particular debate since I'm more of a use-the-right-tool-for-the-job sort. These can range from the highly structured and precise to a less formal, natural language. A precise model helps, for example, when specifying the interactions between two instances, such as a network protocol. These forms can express the how of a design very effectively because they are, in a sense, only one step removed from the actual code expressing that design. They do not, however, explain the why of a design.

Natural language is inherently less precise, but it is far richer at expressing concepts outside of the actual design. In a building analogy, the architect may have a design that shows exactly how the atrium is framed and supported, the lighting characteristics, and many other subsystems and details; these all exist in the plans for each specialty. But the architect is equally as likely to have a statement about the purpose of the atrium to draw people into the building, to carry them up stairs, past windows, and many other details. This sort of purpose is best expressed in a non-technical language so that the reader can build a private understanding, one that will serve as the foundation for understanding the rest of the design.

This becomes much clearer as broader audiences for these documents are considered. While the engineering staff might appreciate a precise document that spells out exactly how a component should behave, the rest of the team has different needs. As the design trickles out from the original conception to the organization as a whole, the requirements for communicating with each new audience become broader. It is rarely necessary to take a low-level design document to a customer, but it is often helpful to have the requirements in a form that is both understandable to a diverse audience and written in a way that can appeal to the audience at many levels.

Recently I was asked to review a design document from another team, a proposed change that would affect a number of components. The document was incredibly detailed, specifying virtually every changed function, the memory footprint, load order—all carefully researched. One thing that was missing, however, was a statement of why this change was being made. While all the provided data looked good, there was no framework in which it could be evaluated. The engineer on the project was so deep in the work that he assumed that all the readers would know why the changes were being proposed. This was a document that would benefit greatly from an introduction (in a natural language) that set the picture for the changes being proposed (in a highly structured language).

Writing is not something to be viewed with dark suspicion by the engineers. Writing is an important part of the job: you need to be able to communicate information to others in order to create complete products. While some forms may be more comfortable than others, the real requirement is that the reader receives and understands the message. After all, if you can't make yourself understood in something as soft as a natural language, what chance is there that the completely precise and unforgiving computer is going to give you the results you want?

Richard Ward is a Distinguished Engineer at Microsoft and runs the Core Architecture team as part of the Core Operating Systems Division where he often writes long documents.