Thursday, February 26, 2009

I need a corporate blog



Whenever someone looks up a piece of documentation regarding our product (the much appreciated IBM XIV Storage System), they don't look for "anything written by avi aharon", certainly not for "the latest and greatest from avi aharon, the later the better". (Although, I must admit, to be asked whether I published "anything interesting lately" is a question I'm willing to be asked on a daily basis.)
Technical documentation is signed by the company, not by the individual who writes it, and for a good and obvious reason. However, I aggregated links to whatever I published in a blog format (that is, last in - first seen).
Why is that?

We have a publication center that is organized by topic (product, or technology). We also have internal websites for drafts we don't delete, to allow for historical research. One way trace the history of a certain feature as reflected on the way it was documented. This is much easier than scanning the code, not to mention design documents, or specs.
Yet, I added this sorted-by-date page.
The reason for this is obvious: the easiest way to find what's new is to look at the top of the page. This is better that compare versions of a wiki page (this website is wiki-based), even better that to look at your RSS reader (my reader feels most comfortable when it's "over 2000 items unread").
The most important feature that information could have is the ability to be easily found. Then comes relevance, then comes accuracy and completeness.
This is easily achieved when you have developers who document what they develope all by themselves, of course :) The top five documents on the screenshot above, the longest of them is 36 pages long, were all written by the developer. I heavily edited them of course, but was amazed by their clarity, accuracy and conciseness.
Such developers make my life so easy that all that is left for to do at work, is to blog.

No comments: