October 14, 2010
|
Documenting ASP.NET Razor
|
103770 hit(s)
One of the design principles of WebMatrix and of ASP.NET Razor syntax is to keep things simple and friendly. Among the ways in which this is implemented in the UI, for example, is to focus on only the current task. Certainly the WebMatrix IDE is stripped down in comparison with Visual Studio, and the combination of workspaces (site vs. files vs. database vs. reports) and the ribbon provides a pretty painless way to switch task areas and keep the options relevant to what you're immediately interested in.
Files and Database workspaces
If you are a student of such things, you'll also notice that the tone of the thing is several clicks friendlier than what you might be used to from (again) Visual Studio:
The K.I.S.S. principle applies to Razor syntax as well. Helpers try to distill tasks like sending email or fetching data or rotating images down to as small an API as possible. I mean, consider this:@{
var db = Database.Open("SmallBakery") ;
var grid = new WebGrid(db.Query("SELECT * FROM Product ORDER BY Id"));
}
<html>
<head>
<title>Displaying Data Using the WebGrid Helper</title>
</head>
<body>
<h1>Small Bakery Products</h1>
@grid.GetHtml()
</body>
</html>
This is (for ASP.NET) an astoundingly compact way to produce this:
The mandate for simplicity and friendliness came down to us in the documentation crew as well. What would you normally expect to see for official documentation for some new ASP.NET feature? Here's a pretty typical section of the ASP.NET documentation on MSDN:
Let's see ... a content map, an overview, some walkthroughs, some drill-down topics (e.g. [All About] Controllers and Action Methods), maybe (not here) some how-to topics. (You would also expect that lurking in the background there'd be an exhaustive API reference, which is our bread and butter docs.) Moreover, the docs would have that standard Microsoft Developer Division tone to them which has been honed over the years for a certain balance of precision, professionalism, neutrality, accessibility to non-native readers, and so on.
This was not going to cut it for the target audience for this new, simpler, friendlier product. What emerged was what we ended up calling the ebook: a set of tutorials (chapters, really) that were organized very much the style of a book:
We were highly conscious of the intended audience ‚ folks who were not starting off as developers already and who would be best served by documentation that was simple, to the point, and friendly. Some of the structural notions we bore in mind were:- Assume no previous experience other than HTML.
- Keep tutorials (chapters) as short as possible.
- Focus on scenarios, not features. (Tho of course these did at times overlap.)
- Cover was what most users would find most useful. (A kind of 90/10 variation on the 80/20 rule.)
- Reduce text to the essentials. (Especially, prune out text that's just glue or is just there by convention.) For most chapters, the user should be up and working on something well within the first page.[1]
This was not nearly as easy as you might think, for a couple of reasons. One is that most of us have spent most of our careers dealing with readers who are, by definition, already programmers; in many cases the sorts of in-depth information we were skimming over are precisely what matters to that audience. (There were times where our cutoff for what to document was right about where things were getting interesting. : -) )
Another problem for us was that this was a new approach to many of us, and it's tough to break some of those habits that the editor has, over the years, beat mercilessly into us. And finally, in our Beta 1 release, we had six writers involved, and you can imagine what it's like for that number of folks to turn on a dime, writing wise, and crank out a new type of thing.
There were definitely some challenges. One of the trickiest was the effort (Chapter 2) to try to teach programming syntax to a non-programmer audience in some reasonable number of pages. This was material that often gets 4 or 5 entire chapters in an introductory book, and we were keen to keep the chapter to 25 pages or less. (We missed, but close.) One compromise was to start off with a Top 8 Tips list that we reckoned covered the absolute essentials.[2]
Another challenge was how to deal with some of the inevitable complexities that we simply had to mention – HTML encoding, OOP, database basics and SQL, even GUIDs – because they came up in the course of the scenarios. Here we used sidebars – optional info for those who were interested.
Anyway, blah-blah. Coming soon, some details about tone, and a quick tip about API ref.
|
|
