Saturday, 8 November 2008
06:39 PM
In the latest MSDN magazine Richard Ward has a column titled "Engineers Who Write." It might also have been titled "Writing for engineers." Ward's thesis is that engineers need to be able to communicate in writing, and that this is harder than being able to communicate in person. One of things he sees in engineering documents, he says, is this:
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. Emphasis mine. I have seen this approximately one (1) million times. Not unexpectedly, I almost always see it (don't see it?) in feature specifications, where (as Ward says), you find lots of detail about how to implement the feature, but very, very rarely do you find an answer to the question "What problem does this feature solve?" To the author of the document, and presumably to the immediate intended audience, this question has already been answered.
Ward makes a particularly salient point about how this type of information becomes less obvious, hence more necessary, as a document goes out to a wider and wider audience: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.  To pick one particular example, the very early documents for the ASP.NET MVC framework assumed that the audience already understood the MVC pattern and was interested in applying it to ASP.NET. (My guess is that overall this was a pretty small slice of the ASP.NET developer base.) As such, the documents did not contrast MVC with the alternative (Web Forms), nor provide any reasons for why a customer might choose between these models. The early docs dove straight into URL rewriting, mock objects, exposing controller methods, and so on -- in other words, they were aimed straight at an audience that already understood the overall approach and just needed implementation information.
As MVC was unveiled at conferences and in preview releases, it became clear what sorts of issues customers were raising. Does MVC replace Web Forms? No, we had to clarify. What do you use for the view leg of the model? Oh! ASP.NET pages. In other words, as the information went to a wider audience, fewer of the assumptions inherent in the design were obvious.
Over time, we've filled in a lot of these holes. What is MVC, anyway? Why is it useful? How does it contrast with Web Forms? Included in this last, tho you won't find it stated in exactly these terms, was an explanation of "What Web Forms problems does MVC solve?"[1]
I cannot count the number of times I have said to a writer "Tell me what I need to know if I walk up cold to this technology." By the time I finish reading the first page of a document that describes a technology, I expect to know why I should be interested in it. You'd be surprised how often that doesn't happen.
[categories]
writing, aspnet
|
link
|