Monday, May 3, 2004 3:24 PM
Working with a new user control, some experiences and lessons
Or I might subtitle this one “RTFM more carefully”
Over the weekend I began some initial trials of a custom server control for the purpose of writing a review. I won't name the contol here, but when the review comes out it will be obvious what product I'm referring to here.
Anyway, I started out the way I always do with something like a new control. I installed it and got it configured in a project. Then I created the simplest page using the control I could, and without referring to the documentation. A moment or two of looking at the property sheet, and it was pretty clear how to configure the control for the simplest case, so I did that, then added a couple of lines of code in code-behind to populate the control. All worked. So far, so good.
So next I decided to try an example of a case that would be one of my reasons for buying the control. Since this was more complicated, and involved multiple controls, and there wasn't anything like an example in the documentation, this time took considerable trial and error, but no matter what I did, I kept getting the same error at runtime. Finally I emailed the developer, and he spotted my problem immediately, and confessed that he probably needed more and better examples.
The fact is, if I had just looked at that Property page a little bit more carefully, or read the included help file a little more carefully, I would have figured out my problem. But, being basically lazy, I hadn't. Shame on me. RTFM, stupid.
BUT: the developer is also correct. There should have been more examples. The few examples that were included were the most trivial. The more advanced features had no documentation beyond the listing of methods and properties in the help, which did not include any sample code.
- To users of a product: I really have to kick myself, but also I'll lecture those who aren't inclined to pay much attention to the documentation-- RTFM. Especially if you try something and it doesn't work as expected. No matter how sparse the help might look, look it over carefully. It may contain just the nugget you need. Give it a try before whining to someone else like I did.
- To product developers: I don't give a %&**!! how neato-keeno your feature set is. If you don't include adequate documentation and examples (preferably working examples that install with the product), users are going to miss some of your best features, or decide they don't work, or are too hard to use. Take the time over the details.