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.

Thursday, February 19, 2009

Dire times indeed

Discussing the dire times of the Israeli high-tech industry, Paula Stern says technical writing is going "no where fast". She has recently conducted a survey saying there are much more unemployed writers that there were several months ago. I have no information that contradics these numbers. Obviously, they sound reasonable. For example, they fit into the fact the a start-up company I had worked for a year ago, no longer exists.
What is the technical writer expected to do when the times get hard?
Paula says: learn DITA.
I'd refine this, and add: increase your vauability to the organization that pays your salary. I am for facing your clientle, you boss, whomever and boldly ask what would they like you to do in order to improve their business.
no onwe is likely to say they need 12 new user guides, 200 pages long each, and hand you a payment in advance. However, they're likely to help you help them to do a little better business.
Several years ago - where business were OK - I was asked to convert an 1000 topics-long RoboHelp project into FrameMaker. As profitable as this project may be, I told my employers there is no reason to convert, as Frame is less productive than RoboHelp. My assertion is questionable, of course, and I know there are many Frame fans that would love to fry me for this. However, with the customers in mind, you simply don't let them to do such a conversion. If the customer is eager to spend 1000 hours on documentation, they have to know there are several other ways to spend this budget and maybe gain things they never dreamt of.
This story took place in 2006.
Today, no one is expecting to gain more from their documentation, but they will be happy to gain whatever they are currently gaining, with half the budget. I say, go ahead and let them. Find ways to double your productivity. Ditch lously tools; learn new tools really fast; use Word if it works for you (although no writer that respects himself uses it any longer :)
Keep your customer in mind, and you'll make it past this dire times.