MSDN Magazine - November 2008 - (Page 120)

{ End BrackEt } RichaRd WaRd Engineers Who Write I was somewhat amused when the MSDN Magazine staff asked me about the purpose of the atrium to draw people into the building, to write a column. There was an initial trepidation, as if engineers to carry them up stairs, past windows, and many other details. This were not expected to write and raising such a request was inviting sort of purpose is best expressed in a non-technical language so that some sort of surly response. This happens more than it probably the reader can build a private understanding, one that will serve as should, but it indicates a more general issue. the foundation for understanding the rest of the design. Engineers—and indeed everyone involved in creating software— This becomes much clearer as broader audiences for these docuneed to be able to communicate verbally, and that doesn’t mean by ments are considered. While the engineering staff might appreciate speaking. Oral communication is great; having a small set of people a precise document that spells out exactly how a component should hashing out details on a whiteboard or over lunch behave, the rest of the team has different needs. As is an invaluable part of completing the design. The Check It Out the design trickles out from the original conception rapid interaction allows everyone to bounce ideas to the organization as a whole, the requirements for See Richard Ward’s “Behind around and get immediate feedback. But it is, by its communicating with each new audience become the code” interview at nature, imprecise. The understanding developed dur- channel9.msdn.com/ broader. It is rarely necessary to take a low-level deing the conversation and the shared context built Shows/Behind_The_code. sign document to a customer, but it is often helpful by the participants rarely extends past the converto have the requirements in a form that is both unsation. Only what is written down can be used by derstandable to a diverse audience and written in people outside the conversation. a way that can appeal to the audience at many levels. Writing down ideas and concepts is essential to the development Recently I was asked to review a design document from another process. While there are many schools of thought on what con- team, a proposed change that would affect a number of components. stitutes the right level of design for a software product, ultimately The document was incredibly detailed, specifying virtually every some aspects of the design must be written down. And much like changed function, the memory footprint, load order—all carefully the notion that no backup product is good unless you verify its re- researched. One thing that was missing, however, was a statement store abilities, whatever is written down must also be readable by of why this change was being made. While all the provided data the intended audience. If someone reads the document and can’t looked good, there was no framework in which it could be evaluunderstand the goals, or worse yet, gets a completely different un- ated. The engineer on the project was so deep in the work that he derstanding, then the process has failed. assumed that all the readers would know why the changes were beThere are a lot of opinions about what should be used when ing proposed. This was a document that would benefit greatly from writing engineering documents. I’m not going to stir up that par- an introduction (in a natural language) that set the picture for the ticular debate since I’m more of a use-the-right-tool-for-the-job changes being proposed (in a highly structured language). sort. These can range from the highly structured and precise to a Writing is not something to be viewed with dark suspicion by less formal, natural language. A precise model helps, for example, the engineers. Writing is an important part of the job: you need to when specifying the interactions between two instances, such as be able to communicate information to others in order to create a network protocol. These forms can express the how of a design complete products. While some forms may be more comfortable very effectively because they are, in a sense, only one step removed than others, the real requirement is that the reader receives and from the actual code expressing that design. They do not, however, understands the message. After all, if you can’t make yourself unexplain the why of a design. derstood in something as soft as a natural language, what chance Natural language is inherently less precise, but it is far richer at is there that the completely precise and unforgiving computer is expressing concepts outside of the actual design. In a building anal- going to give you the results you want?  ogy, the architect may have a design that shows exactly how the atrium is framed and supported, the lighting characteristics, and many RichaRd WaRd is a Distinguished Engineer at Microsoft and runs the Core other subsystems and details; these all exist in the plans for each Architecture team as part of the Core Operating Systems Division where he often specialty. But the architect is equally as likely to have a statement writes long documents. 120 msdn magazine http://channel9.msdn.com/Shows/Behind_The_Code

Table of Contents Feed for the Digital Edition of MSDN Magazine - November 2008

Contents MSDN Magazine - November 2008 Toolbox CLR Inside Out Data Points Cutting Edge Security Briefs Test Your Security IQ Agile SDL Access Control Utility Spotlight RIA Test Run Wicked Code Foundations Team System End Bracket

MSDN Magazine - November 2008

For optimal viewing of this digital publication, please enable JavaScript and then refresh the page. If you would like to try to load the digital publication without using Flash Player detection, please click here.