Wednesday, December 24, 2008

Effective Technical Blogs

In this blog post, I will list and briefly describe some of the characteristics that I have observed to be common among many of my favorite technical blogs. I try to incorporate these ideas into my own blogging, but being aware of these advantageous characteristics does not always translate to me following them as well as I would like.

There is no shortage of ideas on what makes an effective blog. Related resources include The Seven Habits of Highly Effective Blogs, Fifty Habits of Highly Effective Blogging, Eight Tips to More Effective Blogging, Ten Habits of Highly Effective ProBloggers, Aristotle's Top Three Tips for Effective Blogging, Ten Effective Ways to Get More Blog Subscribers, Ten Tips for Effective Blogging, Thirteen Steps to Successful Blogging, Characteristics Required for Successful Blogging, How to Write a Successful Blog: Top Ten Tips, Five Tips to Create an Effective Blog Post, and Five Blogging Secrets for a Successful Blog. The majority of these focus on blogging in general or on business blogging in particular, but there are still many general concepts that apply to technical blogs specifically. These posts also tend to focus on an effective blog being measured by the number of subscribers.

For this blog post, I am going to shift my focus slightly from necessarily striving for the largest number of subscribers to focus instead on effective blogs in terms of usefulness of the entries to readers whether they be subscribers or stumble upon the blog post via search engine or link. For purposes of this blog post, an "effective technical blog" is one that either answers a question, links to something that answers a question, or provides new technical insight to the reader. While my focus is on a blog that provides high value rather than one that has a lot of subscribers, it is not surprising that a blog that consistently provides high value will often see an increase in terms of regular readers as a natural byproduct of that value.

Before getting into the characteristics I have seen to be common among my favorite technical blogs, it goes without saying that perhaps THE most important characteristic is quality of content.


Make Your Blog Posts Easy to Find

Great content is next to useless if no one is aware of it. Powerful search engines such as Google's search engine have made it easier than ever to find things on the web, but I find that there are still times when I cannot find exactly what I'm looking for due to terminology issues. A blog author can help here by uses different descriptive terms in his or her blog post for the same topic to increase the chances of the blog entry being found via search engine. An important caveat is that it is most helpful when the blog author uses the correct terminology and accuracy in names so that correct information is propagated. However, subtle references to other likely used names and terms for the same concept can help trigger search engines to find the posting.

For example, in my previous posts on the Java Persistence API (JPA), I have tried to use the phrase "convention over configuration" (a phrase commonly associated with Ruby on Rails) in addition to the phrase "configuration by exception" (more commonly associated with JPA). The reason for this is that someone may be searching for that general idea, but may type in "convention over configuration" with JPA in the search engine rather than "convention by exception."

It is no secret that Google has the most widely used search engine. This was one of the criteria that led to me selecting Blogger as my blogging platform. An advantage of using Google's Blogger is that my blog posts are almost immediately available on the Google search engine after I post them.

Another way to make your blog entry more discoverable is to create links to it. There is some controversy surrounding whether one should submit and/or vote for one's own work at the various social aggregation sites such as DZone, Digg, etc. I personally prefer that my blog postings only be submitted to these sites if at least one other person finds them worth posting, but I don't hold it against someone who submits and/or votes his or her own blog posting. This can be an effective technique because the social aggregation site is more likely to be discovered by a search engine and because the link on such sites to a blog post will increase the importance of that linked-to blog post in the algorithms of many search engines.


Version Your Post

It is easy to focus on the present and neglect the future reader. One of the most frustrating experiences I have encountered when trying to learn how to do something or resolve a problem is when I stumble across a blog entry without any obvious date of the posting. It doesn't help to have the current date (I generally am aware of what day it is) without the date of the original posting. It is even better if the date is supplemented with versioning information. For example, it is helpful to know if a code snippet or other piece of technical information applies to JDK 1.4.2, J2SE 5, or Java SE 6. It may be really obvious at time of your posting which version you are talking about (especially if it is the current latest production release), but it might not be nearly so obvious even in the near future.


Give Credit Where Credit is Due

I have read several blog entries that seem to be closely related or even inspired by another previously released blog posting. Not only is it more ethical in such cases to link to and reference that blog post, but it can also be of tremendous value to the reader. A reader who likes the post will probably like the original as well. There may be a different perspective in the original post. More than once, I have found that "little piece of missing information" in a blog entry referenced by the one that came up in my search engine query. In other words, my search engine query hasn't directly led me to the answer I was looking for, but someone's blog posting has been the helpful bridge that linked me from the search engine to the results I was looking for. As mentioned above, linking to useful related sites will benefit the one being linked to in search engines' rankings. If that site or blog posting has been helpful or inspiring, it seems the least one can do in appreciation is to link to it to help increase its exposure.


Don't Assume Everyone Knows It

Some people believe that all blog entries should provide all new or mostly new content. However, my experience has been that it is helpful to have the same information presented multiple times as long as the blog entry author puts his or her own perspective on the topic and, as discussed in the previous tip, provides references to the original material.

As evidence of this principle, I have noted that two of the more successful recent postings on DZone have been to blog entries covering topics that some of us have been familiar with for some time. However, they have still been widely popular because they obviously provided the first exposure of that topic to a number of readers. Had the authors of these blog entries decided not to post because it was an "old" topic, several people would have missed out on the information.

Classpath wildcards for JAR files in Java SE 6 have been covered for some time, including in Mark Reinhold's blog entry Class-Path Wildcards in Mustang that was posted on 15 February 2006. This tip has been re-posted many times since then, including here. I have referenced it as a sidenote in some of my own blog postings such as this one on the JMX Web Services Connector. However, it was interesting to see how popular this December 2008 post on the topic was and how many people were introduced to this via this post.

Similarly, one of my most popular blog entries on DZone (as measured by Up votes) was my post on using the Java 6 Deque. This post received more Up votes (17-0 at time of this writing) on DZone than most of my blog entries on far newer and more unique posts.

Part of the explanation for this is that many people don't have the luxury of adopting the latest product (Java SE 6 in this case) when it and all of the introductory blogs come out. In such cases, it is helpful to have a current posting on the topic once the developer does start using that product or language. One might argue that a person could search for this via search engine, but what would prompt one to think to query for a multiple JAR classpath inclusion mechanism? Another could argue that a developer adopting Java SE 6 should read all pertinent documents on the language upgrade, but the reality is that many of us don't read the manual first.

I am not saying here that one should simply provide a link to another blog entry without any additional insight. Rather, a link to an original site with some additional commentary on why this has been helpful to the blog author is acceptable (to me at least) and can actually be helpful in terms of pointing me to that original work.


Separate Personal from the Technical

I have read some very good blog entries on blogs where personal stories are mixed with technical information. While this does not necessary affect the quality of the individual posting on a technical matter, it does make me less interested in subscribing to or bookmarking that blog. Further, the personal information can be distracting and make it more difficult to separate the technical from the personal. This is especially problematic if the two are mixed in the same blog postings.

I don't know (at least not very well) most of the people whose blogs I read, so I am generally not very interested in personal, unrelated details. I prefer to read blogs where the technical blog is clearly separate from the blog author's personal blog. This allows friends and family, including those with no interest in software development, to enjoy the personal blog while software developers who do not really know the author well can focus on the technical blog.

There are exceptions to this; I have seen very effective technical blogs where significant personal issues or stories have been mentioned because they explain something else on the blog or the blog author's status or because they provide an object lesson for or feed-in to the technical subject of the blog. Also, a personal interest used as material to demonstrate a technology can be very helpful. For example, showing how to build an inventory program for Blu-ray discs can provide a nice introduction to a technology. Similarly, explanation of a personal situation leading to a discovery or to a need that is satisfied by the described technical topic can also be effective.

The thing I least like to see in a technical blog entry is political opinion unrelated to software development. There are plenty of politically-oriented blog entries on the web for those who want to read that type of material. For me, political commentary is a distraction from the technical information I am seeking. Also, political commentary is often a sign that the blog author has forgotten that the people reading this blog are potentially from all over the world and often don't care about the political topic being discussed.

There are political topics that can be appropriate in a technical blog if the political issue is related to a technical topic. For example, it seems appropriate and relevant for a software development blog to cover political issues such as advantages and disadvantages of software developer unions, benefits and costs of offshore development and outsourcing, open source regulations and laws, and intellectual property laws. It is also relevant (and often very interesting and insightful) in a technical blog to post blog entries regarding politics associated with software development communities (such as the Java Community Process) and with standards committees.

In general, most of us know where to go to find political blogs. What we need from technical blogs is not more political opinions, but rather is technical insights of the blog author. While a blog author is certainly free to post whatever he or she likes, he or she can create a more effective technical blog if the temptation to stray into unrelated personal and political topics is avoided.


Explain Abbreviations and Idioms

It is easy to forget that a blog posted on the web has a worldwide audience. I have been repeatedly expressed by the ability of many developers with a native language other than English to read, write, and speak English. For example, the European attendees (not just those from Great Britain) at Colorado Software Summit 2008 that I spoke with regarding my presentations spoke fluent English and seemed to keep up with my very fast-paced presentations given in English.

Even for these people who have mastered English as a second (or third) language, we often use cliches and idioms that may not express to them the same nuances they express to those of us who are more familiar with the idioms. Furthermore, even developers whose first language is English may not understand or be aware of idioms and cliches from other nations or even other regions of the same nation. Finally, I have even had fellow developers from the same general region as I am from ask me what RTFM or CYA means when they have heard these acronyms thrown out at meetings. In other words, while idioms can quickly convey subtle nuances, they can also be confusing if not explained.

I prefer to not distract from the topic of my blog with a detailed explanation, but I still want to ensure that someone unfamiliar with the idiom or cliche understands any subtlety associated with them. To satisfy both desires, I try to link to an explanation of the idiom or cliche so that the reader who is unfamiliar with it can find additional details on it. This allows the reader who is already familiar with it to move on without needing to click the link or needing to read through or pass over an explanation they already understand. My favorite sites to link to for these explanations include Wikipedia, the FreeDictionary's Idioms and Phrases section, the Phrase Finder, SlangSite, and UrbanDictionary.

In addition to idioms and other such phrases, even generally accepted technical abbreviations should often be spelled out when first used. If nothing else, the spelling out of an acronym might help a reader new to the topic better refine his or her future search engine queries. Some creative blog entries actually apply idioms heavily and effectively, such as the blog entry Ten Programming Proverbs Every Developer Should Know.


Carefully Prepare Title and Opening Paragraph

Many readers will choose whether to read a blog entry largely on the title and, if they get past the title, on the first paragraph. In addition, these pieces of information are often what are posted on aggregation sites and on other blogs that reference the particular blog posting. Because the title and the first paragraph are likely to be repeated on referring sites and blogs, it is best if they provide a good summary of what the blog posting will be about and why a reader might be interested in it. I am a strong believer that it doesn't benefit anyone (author or reader) to deliberately misrepresent a blog posting's content with an unrelated title.

Besides providing material to motivate readers to read the blog entry, the title and first paragraph are also significant because their likely reproduction on other web sites mean these words may get more search engine attention (and possibly a higher ranking) than the original blog entry.


Conclusion

In my experience, the most effective technical blogs have been those that focus on technical subjects, that are easily discoverable even by those who may not know the exact terms to use to find the information, that reference similar resources that might have what I'm looking for, that provide date/version information for future reference, and that provide explanations or links to explanations of concepts that might be too distracting to cover in the same blog entry.

No comments: