aviaharon.com

www.aviaharon.com

A worthless picture?

I'm not going to say it in a thousand words, but this picture (can be found here) got no attention at all.

Something went really wrong here. I wonder what exactly.

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.

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.

On Over-estimation

The Anecdote blog tells of two engineers: an engineers who is 20 years in the business rates himself as "good" while a guy who is only two years in the business rates himself as a professional.
Makes you think, isn't it?
I'd been working on some document for several months, had to put it aside, and returned to it this week. This document - although far for being ready for delivery - is my pride. I love every word in it, and every GIF I patiently crafted from XLS, via Visio (no Photoshop for me, thanks :)
However, there's a lot that needs to be changed in this document. GIF to be improved, text to sharp and clarify, etc.
Why is that?
Because it's the nature of things: every living thing could be improved. Human creation - including documentation (not to mention the technology I'm documenting) - ought to be improved as well. Whatever I'm doing, I can do better.
This is why, if asked, I consider myself an expert. Not because "I don't know what I don't know", but because "I know what I know", I know how I got to know this, and know how to get new knlowledge in the future.

Managing Camtasia Projects

The following notes should help me unify the movies I produce:
Quick-start Movies:

• U:\My Documents\Internal Documentation\Movies\Quick-start - Selecting Time Range


• Movies starts and ends with 5 seconds of sterna_logo (same location)


• Fonts for the movies: Calibri 18, 24, Black.


• Output size: 800x600, maximum quality.


• Size: 49 seconds are 3MB.


• Movie took roughly 2 hours to produce.

I skip the explanation of why movies are better than user guides (more precisely, movies with user guides are better than user guides without movies :)
and goes directly to the problem I have these days: I don't have a template for my movies. They all look roughly the same.
Only roughly.
I would like to make sure they have an identical look and feel (and later: that the viewer will immdediately recognize that the movie was made by me, but this will take a while to achieve).
More posts to come.

Blog-like communication

Tom Johnson argues in favor of organization blogs. I blog myself (via MOSS infrastructure), but... no one reads me. Why is that?

My guess is that is for the very reason our occupation exists: people don't like to read (and write) more that they have to. So, I use my blog mainly for documentation release notes (posts like: GIFs for this manual are kept under this link).

But people on my organization do blog.

They post, and comment to other posts, sometimes as many as 10 posts a day, and numerous comments, as well.

Where so they blog?

Who's the lucky somain that get their attention?

Not at porn-for-the-developer-who-wouldnt-blog.com, of course.

They blog at the defect management application (say, TD/QC, and others).

They post defects, they fix defects, they contemplate on the right way to design and manifest new features, and they do it agily, on the spot, with remarkable results.

They don't call it a blog, so I don't interfere their work :)

As for me? I announce new publication there, as well.

As for my blog? It still contains (useful) lists of GIFs. (useful only for me)