Internal blogs: why you need one

28 Aug 2012

Quite often I find myself writing a small note about a subject: sometimes it grows to the size of an article. I discovered that, most of the times, when it grows to that size, it is worth sharing with other developers.

So, I wanted our developers to access the information I was writing, and possibly to comment on that and generate some discussion. How shall I proceed in publishing this sort of information?

Option 1: Email

One option to let our developers read my ramblings could be to abuse use emails, targeting our internal developer distribution list. Although I can instantly reach every developer in an asynchronous way, it is a very inefficient way to communicate ideas for several reasons.

First of all, I am effectively spamming our developers’ (already overloaded) inboxes. Most probably, when they receive the email, they couldn't care less about the topic. In the best case scenario, the developer will ignore it and proceed with her work, until an appropriate moment to check the inbox comes. Most of the times the average developer, to put it simply, has to delve into an humongous amount of emails, of which statistically only a selected few are really relevant. The signal to noise ratio of email is way too high, which means that your message may get lost.

Let’s imagine for a moment that our company has a very efficient email policy, and only highly relevant content is sent to the right people. Who knows, maybe the company banned the use of CC fields altogether. Our developers actually get to find the email and read it at a convenient time: what will the developer do, if he has any comments? Write a (personal) reply to the author? Write a reply to the whole distribution list (which may or may not go against the "efficient email policy" hypothesis)? Chances are that a discussion will either take place between a developer and the author or not at all. Sure, a developer might actually stand up and walk to the author to discuss it – pffft, yeah sure. Bonus points if the developers sits in the same room. Maybe they will meet at the coffee machine. The point is, do you really want to manage internal information sharing like that?

If those reasons are not enough to turn away from this medium, consider this scenario: a new developer is hired, during the first weeks he asks about how topic X is handled in the application, or what the rationale behind a design choice is. Easy, just point him to the email Jim sent in October 2009, everything is explained in detail there. Oh wait, he never got the email because he was not employed at the time.

Apparently we found out that email is not the right medium for this sort of publication. So why don't we publish it in our internal wiki? (You do have a wiki, right?)

Option 2: Wiki

After all, a wiki is all about quickly editing and sharing stuff. With this solution, we do not need to look for topic X in our mail client, and everyone can access the content. A wiki could work, depending how it is perceived and used by your peers at the moment. I'm supposing that you have a wiki already running – if you don't, consider creating one for easily editing the documentation. The wiki, though, is seen as a collaboration platform and is more about creating permanent content and collaboratively editing it. According to Wikipedia, the essence of the Wiki concept can be expressed through the following concepts:

• A wiki invites all users to edit any page or to create new pages within the wiki Web site, using only a plain-vanilla Web browser without any extra add-ons.
• Wiki promotes meaningful topic associations between different pages by making page link creation almost intuitively easy and showing whether an intended target page exists or not.
• A wiki is not a carefully crafted site for casual visitors. Instead, it seeks to involve the visitor in an ongoing process of creation and collaboration that constantly changes the Web site landscape.

This is obviously not what we are looking for. We would like to have a place where people could publish their thoughts, ideas, technical nuggets, discoveries – the nature of the wiki leaves these out of the door. And that is good, but not useful for purposes that involve users posting opinionated facts and ideas generating discussion. We don't want to write documents in a collaborative way: we want to bring our ideas out. Which brings us to our third option.

Option 3: Internal blog

I am not fond of the definition of "corporate" internal blog. The corporation part makes it sound big, it may make you think that it is useful in a company with a large number of employees. That is not the case –  you can see now that an internal blog can address the previously mentioned needs that exist in companies of any size.

Looking for an old topic that you remember being posted some time ago? Search the blog. Want to provoke discussion? Write a (controversial?) post and let people comment on it. Do you have an idea? Let it run loose.

Why would anyone write a blog post?

All things considered, developers rarely write documentation, why would they want to write a blog post?

Two of the loudest .NET developers that I use to read, Scott Hanselman and Jeff Atwood, have compelling arguments to get developers to blog. The concept at the base of these arguments stems from a thought by Jon Udell: the gist of it is that the time that you have on Earth is limited, which means the amount of keystrokes you have before your time comes is not infinite. When you recognize this and want to treat it economically as a limited resource, you may want to optimize the use of it: why waste your keystrokes for one person only, when you can get the message across a much larger audience and affect a greater amount of people?

For the egomaniacs between us, having articles published under our own name may already be motivating enough. But what about the rest? We may be induced to think that our topics are not interesting enough, or that we may be *gasp* wrong. Are you asking me to publish this? No way, I suck way too much, there are way too many smart people that are ready to criticize me. They will be knocking on my door and screaming "SOMEBODY'S WRONG ON THE INTERNET! Go get him!".

Stop caring. Here's a tip: everybody sucks at something at some level. The only way to improve is to embrace the suck, accept it and move on, keep practicing and you will eventually be an expert. Some people are naturally gifted with the attitude of loving failure, they just keep going at a tough subject until it is not difficult anymore, then the fun is gone and they want to move on. Other people need to train this to reach levels that they never thought were remotely achievable. Malcolm Gladwell wrote that you need to invest 10,000 hour of deliberate practice to become successful in what you are doing. Note that the "deliberate" part of the practice makes a lot of difference, and writing is a huge help to deliberately practice the art and it provides us with immediate feedback and clarity of mind.

Scott says that all developers should blog: I think that every developer should write some notes down, at least. Publishing them in a blog is an improvement over the process of self-improvement, but you can get there step by step, so don't fret, you don't need to publish everything right now.

If you think that you lack the time for blogging, consider this thought also contained in the previously cited post by Jon Udell:

[...] when people tell me they’re too busy to blog I invoke the principle of keystroke conservation. Was the email message you wrote to three people possibly of use to thirty, or three hundred, or thirty thousand? If so, consider blogging it — externally if that’s appropriate, or internally otherwise. Then, if you want to make sure those three people see the message, go ahead and email them a pointer to it.