About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

Here is a thing to carve in pokerwork and hang over your typewriter. "No one will ever complain because you have made something too easy to understand."

Tim Radford



Navigation





<August 2020>
SMTWTFS
2627282930311
2345678
9101112131415
16171819202122
23242526272829
303112345

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 7/27/2020

Totals
Posts - 2626
Comments - 2635
Hits - 2,288,058

Averages
Entries/day - 0.42
Comments/entry - 1.00
Hits/day - 366

Updated every 30 minutes. Last: 7:58 PM Pacific


  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.


[1] I was talking to Brian MacDonald the other day, and he noted that when he started working with C#, everything he read assumed that you were already familiar with C++ or with Java. I noted to him that the early ASP.NET documentation assumed you were upgrading from classic ASP. Assumptions about what your audience knows are especially a problem for 1.0 documentation, it seems.

[categories]   ,

[1] |