April 2007 - Posts

Musings About How Not Write a Technical Book
28 April 07 12:08 PM | Scott Mitchell

Jeff Atwood recently published a blog entry titled How Now to Write a Technical Book, in which he compared Charles Petzold's latest book to Adam Nathan's. In short, Charles's book - Applications = Code + Markup - lacks the color, diagrams, screen shots, and structural elements (like bullet points, tables, sidebars, and so forth) that are found throughout Adam's book, Windows Presentation Foundation Unleashed. To highlight the difference in style/layout, Jeff includes screen shots from both books. Charles's text is drab and gray, Adam's is bright and dynamic. The code looks like it does in Visual Studio; the figures, headings, and bullet points help break up the flow of the text.

Jeff's analysis follows:

“Beyond the obvious benefit of full color printing, which adds another dimension to any text, it's not even close. The Nathan book is the clear winner:

  • It's full of diagrams, screenshots, and illustrations showing the meaning of the code.
  • The text is frequently broken up by helpful color-coded sidebars such as "digging deeper", "FAQ", and "warning".
  • The code/markup snippets are smaller and easier to digest; they don't dominate page upon page of the text.
  • Liberal use of bullets, tables, subheadings, and other textual elements provides excellent scannability.
  • The book has a sense of humor without being obnoxious or cloying.
  • Did I mention it's in color?

“The Nathan book is brilliant. It reads like a blog and competes toe-to-toe with anything you'd find on the web. Petzold's book, in contrast, is a greyscale sea of endless text and interminable code. There are so few diagrams in the book that you get a little thrill every time you encounter one. It also artificially segregates code and markup: the first half is all C# code; it's not until the second half that you see any XAML markup whatsoever, even though XAML is one of the most important new features of WPF, and the one developers will be least familiar with.“

Charles has responded to Jeff's comments via a blog entry of his own titled, The Future of Writing?

“I've been mulling over Coding Horror's analysis of two WPF books, not really thrilled about it, of course. The gist of it is that modern programming books should have color, bullet points, boxes, color, snippets, pictures, color, scannability, and color.

“Does that remind you of anything?

“Apparently the battle for the future of written communication is over. Prose is dead. PowerPoint has won.“

I don't know Charles personally, but from his online reaction it sounds like he is taking Jeff's (constructive) criticism a little too personally. And Jeff's comments do remind me of something - web developers (like myself) who develop very functional but very ugly web applications only to have customers and managers and the graphics guys come in and say, 'Holy crap, that's an ugly website, we need to add some icons and background images.' When this happens, there's two ways to response:

  • Take their suggestions/comments/changes as an insult to your web development skills, or
  • Realize that you do some things well (backend web development, data modeling, software architecture, etc.) and there are other things that you are not so hot at and others excel at (layout, design, usability, etc.).

Charles response sounds similar to the discourse you'll hear from a coworker who decides to response to criticism on his website's layout using option #1 above. And just like that coworker, Charles is wrong. Design matters. It doesn't trump functionality, but it does matter as design affects usability, which, for a book, is its readability. As one commenter in Jeff's entry wrote: 'I have both books and Petzold's book actually made me loose interest in WPF. It's just depressing to read that thing.'

Adam Nathan's book is published by Sams Publishing, which doesn't surprise me. I've written all but one of my books with Sams and their editors have always encouraged using different elements to break up the flow of text, be it figures, bullet points, notes, sidebars, warnings, code listings, notable quotes from the book's text, and so on. When submitting chapters for review to my editor at Sams, I found that if I had a page or more of solid text, I'd get a comment suggesting various elements to break up the text. And while my technical books with Sams were all in gray scale, I also wrote a book for Sams for the beginners market titled, Create Your Own Website. This book was in color and on every other page (or so) the margin included a sidebar that had further information or ideas for developing their own website or online tools they could use (such as validators, free images and clipart, free design templates, and so on).

For more on this discussion on this topic, check out the comments in Jeff's blog post. There's also a good entry by Phil Haack: Prose Is Dead. Long Live Prose.

(An aside - Jeff provided his own constructive criticism at my last book's title in his post, Teach Yourself ASP.NET 2.0 in 23 Hours, which highlights the flaws in titling books Learn X in TimeUnit. And while the naming scheme does have its drawbacks, I vehemently disagree with Jeff's final conclusion 'that books with titles like Teach Yourself ASP.NET 2.0 in 24 Hours cheapen our craft.' My response was a long-winded blog entry titled, Can You Learn ASP.NET in 24 Hours?)

Filed under:
My Upcoming Hiatus
28 April 07 10:52 AM | Scott Mitchell

Over the next several months there will likely be a severe shortage of blog posts here at ScottOnWriting.NET. My wife and I are taking a bit of a sabbatical this summer and doing a lot of traveling and hiking. During this stretch - from about now until late September - my ASP.NET work will be curtailed to only include writing my weekly article for 4GuysFromRolla.com and my monthly Toolbox column for MSDN Magazine. Seeing as I try to keep this blog's focus on technology, .NET, and writing, I don't anticipate much content will be added here until our return. Any trip-related blogging will be done on my personal blog site, ScottOnLife.com. The most recent entry, The Upcoming Summer of Travel, provides more detail on our trip, for those interested.

On a slightly related note... when I first started this blog back on July 2, 2003 (see the first post), I used Scott Watermasysk's .Text blogging software. Since then, .Text has turned into a much more feature-rich and mature product called Community Server, which also includes features like galleries, forums, and so forth. However, I've stuck with .Text throughout these years, mostly because .Text worked. Updating was a low priority and work kept me busy. Anywho, as I started winding down my writing and consulting gigs in anticipation of our travels, I ended up with some free time on my hands and decided to convert ScottOnLife, which was also running the same antequated version of .Text, to the latest and greatest version of Community Server. I've still got some rough edges to work out, like ensuring that the old .Text links still work and don't 404, but overall the transition went fairly smoothly. But once those get resolved my plan is to upgrade ScottOnWriting.NET, too. I am a little doubtful that this will happen prior to the start of our trips, but I write it here to sort of make sure I make this conversion when we get back in September/October. :-)

Finally, I get a lot of emails from people asking when the next set of tutorials will be published in my Working with Data in ASP.NET 2.0 series. There are currently 57 tutorials published online at www.asp.net, but I have written 75 in total. Those will appear on the site over time, based on the availability/schedule of the folks maintaining the www.asp.net website. I have been told to expect the next batch within one to two weeks, but nothing more specific. Wish I could provide a more definitive timeline. In any event, you can always subscribe to the tutorial series's RSS feed so that you will know when new tutorials are published.

See you in September!

Filed under:
Lessons Learned from Running a One-Day Conference
23 April 07 09:59 PM | Scott Mitchell

Over the years I have spoken at a number of user group meetings and conferences and have been teaching at the University of California - San Diego Extension since 2001. In all of these instances, my primary responsibility has been to speak, present, and teach. I have not had to worry about the plethora of other concerns, such as: advertising or marketing; procuring a venue; handling sign ups and collecting and processing payment; providing printouts; arranging for catering; ensuring that comforts like snacks, water, coffee, and soda were available to attendees; and set up and tear down. All of these responsibilities became mine when I decided to put on a one day conference/training event back in February of this year. This event was held on Saturday, April 21st, and I'm happy to report that it went off as smooth as I had hoped for in my wildest dreams.

I learned so much from this experience and wanted to share some lessons learned from my experience for those interested in arranging their own developer-related conferences, events, or user group meetings. Note that the event held this past Saturday had 48 attendees. My comments and suggestions might not apply of be applicable for significantly smaller or larger events. Also my advice is geared toward those who are putting on such an event by themselves or as part of a non-profit group and that they don't have the resources of a large company to tap into.

Marketing and Advertising
I marketed this event in the following ways:

  • Direct interaction. I do consulting and training work for some businesses local to San Diego, and told them of this event in person
  • Via this blog
  • By emailing my past UCSD Extension students
  • Attending the ASP.NET SIG meeting in March here in San Diego and promoting the event
  • Asking Dan Mathson and David McCarter (who help run the ASP.NET SIG and San Diego .NET Developer group, respectively) to email their email lists with a blurb announcing the event

Unfortunately, I didn't keep detailed statistics as to what source my sign ups came from, but based on the dates of the sign ups I can make educated guesses as to the marketing campaign that resulted in the sign up.

As the following chart shows, the emails coming directly from Dan and David were, by far, the largest source of attendees. The second largest source of sign ups was from emailing my past UCSD students. While Dan and David's emails provided a larger total number of sign ups, the emails to my students had a much higher sign up rate. Dan and David sent emails to nearly 1,800 local developers for a conversion rate of about 1.5%, whereas I contacted less than 100 past students for a conversion rate roughly ten times higher.

Note that no one signed up from the user group meeting promotion. My guess is because the conversion rate here is on par with the email blast (~1.5%). In short, my results show that it is more cost effective to focus on getting the word out in less personal ways to a larger group than to make a person presentation to a small group. Of course, all forms of marketing should be pursued, time permitting, but if you have to focus on one, a far reaching email blast seems to be the best route.

I did not spend any money on advertising.

Since large scale email marketing appears to be the most effective marketing tool, talk to local User Group leaders about promoting your event. Also, if you are doing an event about Microsoft technologies, get in touch with your local Microsoft Regional Director for suggestions and help on promoting your event.

Procuring a Venue
Finding and reserving a venue is, obviously, an important step, and needs to be done prior to marketing the event. I had some people with event hosting experience recommend hotels as venues. They usually have onsite catering and rooms to accommodate various sizes. A more affordable option might be to find a local .NET consulting firm and see if they are interested in volunteering their site. If there is a Microsoft office in your city, that might be another option. To be honest, I didn't explore venue options in depth. UCSD Extension was able to offer me a room for the day at a very competitive rate.

One thing that is important is to scope out the room before agreeing to use it. The site may say that it can fit 50 people, but on inspection 50 people might be a tight fit. Also, make sure that the projector, amentities, and facilities are what you expect.

Handling Sign Ups and Processing Payment
Events and conferences should always have a corresponding website that provides information about the event including: a high-level overview of the event; a more detailed outline; and directions. Moreover, the website should allow attendees to register via the web. I created such a website for my event (see http://fuzzylogicinc.net/BlackBelt/). The website was very straightforward, containing only four web pages:

  • Home - provides a one paragraph description of the event, key information (where, when, and how much), and a paragraph about the instructor.
  • Sign Up
  • Outline - a detailed outline of the material to be covered
  • Directions - the address of the venue, directions, and a map

I used PayPal to handle payment processing. After entering their name and email address, the user would be redirected to PayPal's website where they would be prompted to pay for their purchase (either using a credit card, a check, or from their own PayPal account). A more professional approach would be to use PayPal's SDK or some other payment gateway and handle the payment processing logic entirely on the event's website.

Printouts
For my event I provided each attendee with a bound printout of the 300 or so PowerPoint slides examined throughout the course of the day. I initially contemplated doing the printouts on my own, but instead opted to use a print shop. In particular, I chose Kinkos because they were within walking distance of my home and they have a slick application for submitting your order: namely, you install a program that adds a printer to your system. You then 'print' your slides (or whatever) to this special printer, which launches a program that let's you choose the paper type, whether to use one-sided or two-sided, if you want a binding, color or black and white, how many copies, and so on. It then lets your preview your order, shows the amount due, lets you specify a pickup time, and collects payment information. Very easy to use and highly recommended.

Catering, Beverages, and Snacks
Some venues provide onsite catering, but chances are you will be on the hook for catering. You will have to find a reputable caterer and also provide your attendees with snacks and beverage refreshments throughout the course of the day. For this event, I used Come On In Restaurants, a caterer recommended by the UCSD Extension staff. I had sampled their food at a previous UCSD Extension event and it was quite tasty. I was also pointed to Restaurants on the Run, which is an online directory of 'catering and delivery specialists.' A good caterer will help you craft the menu and will be sensitive to your budget.

You will also need to procure water and soda and snacks for your attendees to enjoy throughout the course of the day. We bought water and soda from Costco. In the end, we bought too much soda and too little water (which is understandable, given my predilection for carbonated beverages). Specifically, we purchased 36 cans of non-diet soda, 108 cans of diet soda, and 70 bottles of water for 48 attendees. We ended up bringing home about 70% of the soda and ran out of water by mid-afternoon. We also grossly overbought coffee from Einstein Bros., which serves 'catering coffee' in boxes that each have 8-10 servings. I bought four boxes of regular and one of decaf, and we ended up going through two boxes in total, throwing out the rest.

We didn't buy snacks, although in hindsight we should have. The caterer provided an assortment of cookies and brownies, which were decimated. Around 3:00 PM, many attendees seemed to be seeing if there were any sweets left over. While the catered desserts were completely consumed (as were the selection of chips), the sandwhiches and pasta and green salad had a bit of leftovers. We brought it all home and had the sandwhiches and salads for three meals before throwing away another couple of meals worth of food.

Setup and Teardown
Hosting an event of this size requires a non-trivial amount of setup and teardown time and energy. In addition to setup and teardown, the beverages and snacks need to be attended to throughout the course of the day. And the caterer may need assistance and/or directions on where and how to setup the spread. Naturally, hosting such an event is not a one-man show, so you'll need to recruit your spouse or a friend or colleague to help out. My very helpful and wonderful wife spent her Saturday restocking the beverages, assisting the caterer, and answering any logistical questions (where are the bathrooms, are there any more cookies, and so forth). She is also an ASP.NET developer, so she could have fielded technical questions!

Final Thoughts
I was pretty nervous the days leading up to this event because of my inexperience at handling all of the miscellany involved. Fortunately, everything went according to plan! There were no 'surprises' and I didn't forget anything essential. I was pleased at the turnout, the quality of the catered lunch, the attendee participation, and so on. The only disappointments I had were minor ones. For example, the thermostat wasn't very effective and the room got pretty warm, but opening a door to the outside cooled it off fairly effectively. And buying too much soda and coffee and too little water.

I had a blast putting on this event and presenting the material, and plan on hosting future one-day events similar to this one on additional topics (AJAX, ASP.NET v3.0/3.5, and so on).

Filed under:
JavaScript Includes - Be Careful With Your Syntax!!
18 April 07 03:40 PM | Scott Mitchell

When adding client-side script to a web page, the JavaScript can be embedded directly within the page's HTML or provided via an external reference similar to include files in programming languages. When using JavaScript include files, the browser will cache the file so that it doesn't need to be downloaded on subsequent postbacks and page visits. By embedding the script directly wthin the page's markup, the script must be downloaded on each page visit (with the rest of the markup), which is wasteful if the script content is static. Therefore, JavaScript include files lessen the amount of data the client must download, improving the end user's experience. So JavaScript includes are a Good Thing. In fact, when using certain ASP.NET Web controls (like validation controls, the Menu, and so on), script includes are used to inject the necessary client-side plumbing).

JavaScript includes have a simple enough syntax:

<script src="pathToJavaScriptFile"></script>

Of course, XML rules allow for elements with no inner content to use “/>” as a shortcut rather than needing the closing tag. In a recent project I assumed this would work for JavaScript includes and added a number of includes using syntax like:

<script src="pathToJavaScriptFile" />

Well, guess what? That doesn't work, at least not in Internet Explorer. IE ignores the JavaScript include altogether, not sucking in any of the JavaScript content from pathToJavaScriptFile. If your JavaScript file contains only infrequently-used functions, you of course don't find this out until you perform some action that calls one of these functions in pathToJavaScriptFile and you end up getting a script error. And then, of course, you spend the next hour pouring over the JavaScript code and the page's rendered markup to find what's wrong, not realizing that the browser hadn't sucked down the JavaScript include file because you used “/>” instead of “</script>”.

What's particularly odd is that if you use a tool like Fiddler to inspect the HTTP traffic, the browser still makes a request to pathToJavaScriptFile! It just doesn't 'execute' the script or 'register' the functions if you end the <script> reference with “/>“ instead of “</script>“. Ditto if you fail to end the <SCRIPT> element (that is, if you have <script src="pathToJavaScriptFile">).

Long story short - make sure you don't make the same mistake I did. Save yourself an hour of frustration by adding the verbose “</script>” when externally referencing a JavaScript file instead of trying to save six bytes by omitting it.

Filed under:
May's Toolbox Column Now Available Online
13 April 07 09:27 AM | Scott Mitchell

My Toolbox column in the May 2007 issue of MSDN Magazine is now avaiable online. The May issue examines three products:

  • NDepend - a program for graphically exploring the interdependencies among methods, classes, and assemblies in a .NET application.
  • ApexSQL Edit - a rich SQL editor with IntelliSense, source control, and other interesting features. Like SQL Query Analyzer on steriods!
  • Cropper - a free screen capture utility; written in C# with the source code available.

This month's issue reviewed How to Code .NET, by Christian Gross. Here is an excerpt from the review:

Most successful computer trade books either focus on a very specific subset of a technology or provide a broad overview of the entire technology. How to Code .NET, by Christian Gross (Apress, 2006), doesn’t fall into either of these categories. While its title implies that the book is a weighty tome on creating .NET applications, its mere 232 pages indicate otherwise. It neither focuses on a specific subset of .NET nor does it provide a sweeping overview. Instead, it provides 30-50 pages each on four disparate topics: Test Driven Development (TDD), low-level .NET runtime and framework information, text-processing tips, and C# coding tricks.

...

At 232 pages, How to Code .NET does not cover any topic in great detail and therefore is not intended for the reader who wants to explore these topics in great depth. But the book provides a well-written, informative look at a smattering of topics. Most intermediate .NET developers would benefit from reading How to Code .NET as it provides a number of useful tips and serves as a good starting point for exploring some of the more advanced .NET concepts.

As always, if you have any suggestions for products or books to review for the Toolbox column, please send them into toolsmm@microsoft.com.

Filed under:
Working with Data in ASP.NET 2.0 - Complete!
03 April 07 12:03 PM | Scott Mitchell

Over the past year or so I've been creating a series of ASP.NET 2.0 tutorials for Microsoft that focus on working with data. These tutorials have been published on www.asp.net and on the MSDN website with the first batch published in June 2006. The Working with Data in ASP.NET 2.0 tutorials were modeled after the tutorial series started by Scott Guthrie and aimed to provide step-by-step instructions (with lots of screen shots) on how to perform common data-related patterns. I use the past tense here because, this past weekend, I wrapped up the final milestone for the data tutorials, turning in the final VB and C# versions of the 75th tutorial!!

At the time of this writing the most recent tutorials to be published were the Working with Binary Files tutorials (#54-#57). The upcoming tutorials examine:

  • Caching (four tutorials)
  • Data and the Site Map Provider (one tutorial)
  • Working with Batched Data (looks at using transactions; four tutorials)
  • Advanced Data Access Layer Scenarios (nine tutorials)

Writing these tutorials was very similar in process to writing a book. I'd wager that the average tutorial is about 10 printed pages in length, so the series is equivalent to authoring a 750 page book. It should come as no surprise, then, that I feel as spent as when sending off the final author review to a publisher. And, like after authoring a book, I am more than ready for a break from this time-intensive writing.

There are plenty of differences between writing a book and writing a book-length online tutorial series, of course. With a book you don't see a physical manifestation of the hard work until many months after the book has been written and reviewed. Online work, however, allows for incremental and quicker publication schedule, which.helps keep me motivated. And while well-publicized technical online material is more accessible and read by more people than a book, there's still something alluring about books... about being able to see a physical manifestation of your work in a bookstore. To see someone thumbing through your book. To hold it in your hands, to skim the table of contents, to turn to a random page and cast your mind back to the days you spent writing that chapter. These sensory delights are nice, but come at a cost, as writing computer trade books very often has a terrible ROI - see The Economics of Writing a Computer Trade Book for a more detailed breakdown of why writing computer trade books is not the way to riches.

Many thanks to those who helped review the tutorials or who have provided feedback or pointed out typos or other issues since their publication. One of the nice things about having an “online book” is that it is much easier to fix typos and update code, if necessary, so keep sending in corrections.

More Posts

Archives

My Books

  • Teach Yourself ASP.NET 4 in 24 Hours
  • Teach Yourself ASP.NET 3.5 in 24 Hours
  • Teach Yourself ASP.NET 2.0 in 24 Hours
  • ASP.NET Data Web Controls Kick Start
  • ASP.NET: Tips, Tutorials, and Code
  • Designing Active Server Pages
  • Teach Yourself Active Server Pages 3.0 in 21 Days

I am a Microsoft MVP for ASP.NET.

I am an ASPInsider.