I've had a two unrelated events in the span of just 24 hours lead me to this minor rant regarding some common issues I've noticed in many technical articles / presentations. It appears that when most authors write articles or presentations, they tend to:
- Focus on the features being taught in as much of a vacuum as possible.
- Paint the technology in a glowing light.
While I can understand the pedagogic (1), and psychological (2) reasons here, I believe that the ease and confidence with which the content is presented can inflict harm on our developer community.
How? Consider the reader's mindset. First of all, they're likely to be implicitly swayed by the author's credentials due to the context of the situation. It's a reputed web site, a developer conference, etc. Second, the positive tone with which the content is presented leads the reader to assume that the author had an entirely positive experience with the technology. This interpretation is further validated by the ease with which the author's straw man succumbs to the power of the new technology.
So off we readers go, secure in the knowledge that this is going to take care of all of our problems. How often have I made this exact error, only to meet with disillusionment when I try to apply the solution to a REAL (even simple) business problem? Sometimes, it is because the technology simply is not ready for prime time. Often the technology is fine, but the article's simplistic problems simply don't illuminate many of the critical issues that you really need to understand in order to apply the technology effectively.
What can be done about this as an author / instructor? Certainly, having been blogging for 1 week, I don't profess to have all of the answers here, but here's a few things I've noticed that seem to help:
- Choose your scope carefully. If you are writing 1 article, choose a small topic you can really discuss thoroughly. Don't try and cover everything. If you really want to cover a large topic, you're going to have to break it out into multiple parts.
- Chronicle your experience using the technology on a real application
- Share the gotchas you struggled with along the way, not just the successes. What you found and solved could save many readers many hours of pain.
- Try to explain what's going on behind the scenes. I don't mean you need to show me ILDasm output. But, if I'm teaching ViewState, I want to make sure readers understand that it serializes ALL of the control state to a string that gets passed BACK AND FORTH on EVERY PAGE HIT, not just the form data itself. I want to highlight specific situations in which this could be a problem, like in a GridView.
As a reader, you may want to consider:
- Buying a book on the topic. They often times do a more thorough job of explaining what's really going on. Around 2002, most of my books were all red (Wrox). Today, I've found that most of my purchases are yellow and black. (APress). As a general rule, the books on narrower topics are a better bet, because they provide more complete coverage than the broad "ASP.Net", or "C#" books.
- Design Patterns. Learn 'em, live 'em, love 'em. This will improve every aspect of your programming life, and you'll be more likely to see the gaps in an article intuitively.