Technovangelism

Thanks to #30:30:30, my motivation for blogging has increased significantly. The first few (ok, maybe first 15) posts were difficult and I had trouble convincing myself to actually write them. Lately writing has been significantly easier and I am enjoying it and finding some value in it. Now that I am writing consistently I have seen my subscribers climb a little (from 0 to the single digits) thanks to FeedBurner. I have yet to really promote my blog myself; Nate and Nick are doing a good job of that. But if my blog ever does get past three readers, a FeedBurner chicklet might be in order.

What impact does a FeedBurner chicklet have on a blog and its subscribers? If I put a chicklet on this site, I’m guessing it would cause more laughter than new subscribers, but maybe someday it could be of value. What is the threshold for a chicklet to help gain subscribers? Is a blog with 100 readers less enticing than a blog with 10000 readers? 1000 readers? A blog with many readers convinces me that not only has it been around for a while, but it will continue to exist and be updated. Unless the author really enjoys blogging, which he absolutely should, not having many readers is a good excuse to put off writing your next post until tomorrow.

Think back to all of the documentation you have ever produced for a single project. Include everything from meeting minutes, requirements and design documents, lists of assumptions and anything that is considered “required” for your project. How many times have any of those pieces of documentation ever been read? If it’s anything like the teams I have been on recently, it is close to zero. Certain kinds get read more often than others, but the collective average is quite low.

What is the point of writing something that is never going to be read? Don’t pay any attention to the number of readers of this blog. Developers are constantly told not to waste time on features that will not provide value for the customer, but we are sometimes forced to write documentation that can provide even less value. Does my customer care that I took meticulous meeting minutes? Do they even care that I made a list of assumptions that should help the next developer who takes over my code? Probably not. They do care that you deliver on what you promise and that development continues to progress well regardless of who is doing the actual coding. So can it be said that documentation provides real value to a customer?

Not only does documentation often provide little to no value, but it gets out of date quickly. If you are one of the heavy producers, go back and read something that was written only a month ago. Not only will this probably be the first time anyone has read it since it was written, but it will not properly describe what your project has become. Any specs or details that were once important to the project will be meaningless at this point. Projects evolve so quickly it is nearly impossible for a document even one month old to hold much weight.

Worthless documentation can be found everywhere, not just in .doc files. Here is a snippet of code (why yes, it is VB) I found, complete with “documentation.” This comment might have been useful in the past, perhaps if the methods had different names or there were a few more lines in between them, but at this point that comment is worthless and was waste of time to write.

  ' Start the module into rotation and restart the timer
  module.StartRotation()
  m_ResetTimer.Start()

Final thoughts: Do I hate documentation? Of course not. But I would rather only write something that is going to read by someone other than me.

I recently asked a question and was pleased to receive an answer that was simple, concise, and worked perfectly.

I was asking about the best design pattern for handling several tiny, but separate scripts to run on page load. Most of these scripts were just providing focus for a specific input element. I didn’t want to write a new javascript file for each tiny chuck of onLoad code, but I also didn’t want to embed javascript directly into the HTML where it is obtrusive and easy to lose track of. An astute Stackoverflower presented me with an option that I consider to be about as perfect as it gets. Please excuse my Prototype, I am slowly working my way into the jQuery world.

Element.observe(window, 'load', function() {
    $$('.focusOnLoad').each(function(item) {
        item.focus();
    });

$$('.disableOnClick').each(function(item) {
    item.observe('click', function() {
        item.disable();
    });
});

});

Now most, if not all of my onLoad code that used to be scattered about my project, is nestled neatly into a single function, located in my project’s main javascript file. Doing this has also increased the usability of my app as before this solution, the amount of time it took to go through the painful task of writing duplicated code everywhere was great enough that not every page with an input had it auto-focusing. Now that I only have to add a single class name in each of those files, it is much easier to go through the project and make each page that much more usable.