GUI Yourself

aviaharon.com

2011-03-24T21:23:00.000-07:00

www.aviaharon.com

A worthless picture?

2009-03-05T05:04:00.001-08:00

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

2009-02-26T07:11:00.001-08:00

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

2009-02-19T04:45:00.000-08:00

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

2008-05-12T00:34:00.000-07:00

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

2008-04-30T03:40:00.000-07:00

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

2008-04-21T02:35:00.000-07:00

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)

Switching to Hebrew

2007-10-15T02:08:00.000-07:00

Focusing on customers, rather than on fellow writers, I have switch to writing in Hebrew, on an Israeli-based platform. From time to time, I find it irresistable to communicate with other writers, so I extensively comment to their posts on their blogs.
My main focus, though, is my next customer. Keeping that in mind, and writing a book aimed at the Israeli hi-tech venturer who would like to recruit a writer, I blog only in Hebrew.
You see, one of the beautiful aspects of being a writer in Israel, is that the customer prefers not to read English at all. This facts defines the Israeli market (along with other factors, though). Writing to my potential customer in English, is like... not writing at all.
Thanks for everyone who've read me so far.

2007-07-09T02:10:00.000-07:00

Katriel of Method M says that DITA is the least worse approach to documentation. I sadly agree. I don't know DITA, so what I am actually agreeing to, is the concept of "least worse". Whenever I find myself telling my managers about the poverty of the tools I use, I end up frustrated. They are willing to open up their check-books, it is me who tells them to save their money, as to be able to write, circulate for feedback and deliver 2000 topics/year, MS-Word is the only tool available.
MS-Word???
Yes, I answer, exactly because it is the least worse tool. Although I write with RoboHelp as a primary source, and CHM a primary output, I admit it is no better than Word.
But there is a solution, say the DITA people.
DITA, they say, will save me from myself. I admit that I don't exactly know what DITA does. It is said to ease the ability to deliver multiple types of outputs. However, I ask, why deliver multiple types of output in the first place? No one read printed documentation anymore, and for on-line readers, no one can tell the difference between PDF and CHM. They're both easy to navigate, search, and find what you are looking for.
Let's take a different angle. Suppose I throw everything I write to a single website. Suppose that this website is well protected (acceessible only to registered users, for example) and well accessible (it takes a fraction of a second to perform a search, and the search returns excellent results). Now, looking, for example, for installation guidelines for some product of mine, wouldn't it be safe to assume that the readers won't mind whether the piece of information they're after is titled "installation guide" or "installation notes for version 1.1.0.35" or "fix to defect #35022"?
If my assumption is correct, piling everything I write onto a single website will eliminate the entire single-sourcing empire (an empire of pit-falls, if I may). No more DOC-to-CHM, RoboHelp-to-PDF. Wow. This is a Wow, no less.
So, this leave me with what Katriel calls "DITA is a standard — and is implemented using topic-centered and minimalism (methodology)". I'd buy this guidlines anytime.

Blogging as a form of Procrastination

2007-06-25T03:13:00.000-07:00

Inpired by this post I am pleased to announce that earlier this month I have shut down two blogs of mine. Yeap, you don't have to be a teen to have multiple blogs aimed at multiple audience.
The two deceased blogs were quite busy. I wrote 3-5 posts a week per each. I t was fun, it was productive, it help me to a achieve a well set goal and learn something about myself, all in a package of a blog that I could shut down just like that.
Mabe that is exactly the point. Sure, blogs are procrastination. But, they are so as a form of documenting scattered thought. (I alomost worte "managing thoughts") Real life - if held correctly - are purposeful. Blogging - if taken to what they are - are everything else. Blogging means thinking freely. Thinking freely means thinking randomly. Randomness won't achieve any goal for me, but it allows me to recreate and to keep track of my thought at the same time.
The next thought that has just popped up is that procrastination is demoting a short-term goal my daily tasks) for a longer one. Longer, and less definite. Now, I don't know wxactly what I meant by this one, but hey, this is what blogging is all about - keeping track of this halfbaked thought in order to be able to return to it later on.

A semi-wiki documentation trial

2007-05-17T03:03:00.000-07:00

I consider myself as "highly pro-wiki, yet the worst salesperson I could think of". I believe wiki is fantastic, yet I fails to pass the argument that an SME * who already reviews a document would benefit from a Wiki platform more that form the MS-Word track changes features that is currently in use.
For several years, I look at such posts with a great envy. Trust, tolerance and confidence are important, of course, but something else is missing. I can't get people to write into a wiki and I can't think of the reason why.
Last week I was asked to write a 2-3 paper one some new feature. It's a command-line operated tool, not very intuitive for me, so I asked R&D for some extra help here. I stored the document on a public domain and send them the link with a general comment that says "please read and comment, thanks".
They were great. Within a day, three developers has commented, raising new questions, answering some other questions, extending the document a little because the feature has evolved, etc.
Of course, I had to go over the text, move some from the comment boxes into the document itself, accept and reject changes, etc. But, the document was extensively written by developers who were happy - and agile - to contribute.
Now, our major documentation set is hundreds of pages long (to each direction :-), so I believe we;ll take it one step at a time.

* This is the guy over the cubicle who is not a tech writer.

tech_writer_blog_directory

2007-05-17T02:58:00.000-07:00

I have added myself to this directory.
Thank you, Anne Gentle of BMC, for telling about it.
Anne's latest posts deal with using Wiki for documentation, a topic I will extensively write about.

Creating an Image Report with RoboHelp

2007-04-26T02:29:00.000-07:00

When I discovered that my primary layot is On-Line Help, and therefore switched from writing with MS-Word to writing with RoboHelp, I have started to hide my screenshots.

Instead of presenting the reader a set of steps that span through several pages, I deliver a 10-rows-long text-only set of steps whose screenshots are hidden behind the text. Clicking a step reveals the screenshots and most of the readers are usually happy with that.

The problem within this arrangement is the way I maintain these screenshots. Ever so often I am required to update the On-Line Help to match the product's new GUI. In some of these cases, only the GUI changes, while the logic (the way the user uses the application) remains intact. Such a screenshot replacement should be a breeze. It is, indeed, very easy, given that I know where my screenshots are.

How do I know that?
Writing into MS-Word, I simply run through the pages, look at the shots and replace them on the spot. RoboHelp is less intuitive here (no such thing as run through the pages...) but it provides an Image Report.
Quickly bypassing the report's pitfalls (Selecting All Folders doesn’t recognize Conditional Build Tags; Selecting a parent folder results in an empty report) we come up with a list of all images per topic. Properly laying out the topics (i.e. one task sequence per topic), the images read task1-image1.gif, task1-image2.gif, etc.

(Blogger allows for a single picture per post, so no more images for you. Come back other day.)

Earlier this week I have copied such a report into an MS-Word file, along with tiny-little-hand-crafted screenshots icons. Too much work.

Generating the report on a daily basis throughout the project, should do.

Flatland - the metaphor works in both directions

2007-04-18T23:42:00.000-07:00

BlogScholar (to whom I have arrived via Commitment to Living) writes that academics should leverage themselves through the blogosphere.
I am not going to add my two cents to the "of course you should have a blog or two, too". Instead, I would like to state that one of reasons I'll probably won't see the university from within is that all I need to know is available on-line.
Sure, there are lots of things I would like to learn. Moreover, there are plenty of things I need to learn (for example, in order to stay in the business).
However, instead of driving to the nearby university campus, guessing whether I have chosen the right professor for my needs, guessing I know what my academic needs are, and keeping them from evolving throughout a 13-weeks long semester, *
instead of doing all that, I am quick-searching a subject, read a post or two (or two-dozens, depends on how long does it take me to get it straight), post several comments with questions, and always get a decent feedback from the blogger.
The land is, indeed, not flat anymore, and it works for non-academics as well.

* OK, no English professor would ever allow me to write such a long sentence. Maybe the university has a point after all ;-)

Selecting an authoring tool

2007-04-16T01:16:00.000-07:00

The technical writer's wet dream looks like this:
"I've recently joined a startup company that has never had a techwriter and needs me to write all the doc from scratch."
Being a wet dream, this question has more that one right answer. However, as I managed not to send my reply to the group (one of the strongest YahooGroups features), I recall it here.
I'd go for constructing a writing culture from scratch. Having my documents reviewed by Markeing / PM / R&D is crucial for their quality. Writing in FrameMaker, PDFing the document and shipping it to R&D for a review, is actually saying "Please don't comment to this document. If you feel you must comment to it, a 'job well done' will do. Here, let me spell 'job well done' for you".
Writing in MS-Word, on the other hand, is far better. Tech Writers don't like Word for several good reasons. However, Word allows for tracking changes in a manner no other writing tool does. Having the document straight with all R&D comments taken care of is far more important than having an FM file nicley * transferred to WWP. **
Tech Writing is a customer facing business. Keeping that in mind makes happy customers. Happy customers make rich Writers.

* I know that 'nicely' is very generous here
** If you don't know what WWP is, count yor blessings

"tech writers will learn to be more independent and entrepreneurial"

2007-03-28T01:42:00.000-07:00

Tom Johnson outlines the future role of technical writers. I agree with Tom ("I share the hope" is more accurate :-) that in the near future, technical information will be gathered via Wikis.
However, I am not sure that what I will be selling would be tutorials and other books.
By "tutorials" I refer to any kind of structured information set. Today, programmers and product managers deliver more structured text than ever before. It is structured, and it is structured in a way the customer would benefit from reading it.
More and more documents requires less and less intervention on my end.
I'd also replace the argument for endless documentation tasks with finding a new purpose for the tech writing role. It is true that "If you’re a tech writer for such a project, the documentation will be like a living child, always growing, maturing, asking harder questions, getting into more trouble" but it can go in opposite directions: let the tech writer boss it all, or forget using tech writers altogether. The writer has to constantly add value to the documented project. Not only to the project's documentation, but to the project itself. (hint: think of usability rather than of the code.)
As for delivering a clean text. The technical world is already writing in Globish. I'd guess it has done so from as early as 1998, but am not sure that it's OK to use present perfect tense anymore.
It all new for us, writers, but the future belongs to the brave, as it has always been.

Five years from today

2007-03-27T02:06:00.000-07:00

The article Google - 5 years from today (Hebrew) claims that within 5 years Google will offer a stronger, AI-based search. Great, of course, but not futurist at all. The immediate analogy is to MS-Windows and MS-Office. Sure, its easier to write user guides on MS-Word 2003 that it was on MS-Word 97. Easier, but nothing more.
I eager for a futuristic view of documentation.
A year an a half ago, when I failed to introduce Wiki to the folks I work for, I introduced it to ... a friend of mine.We met in a pre-birth class, helped our wives to breath-at-command, and moved on to talk about nearly a interesting as topic, naimly, work.
So he implemented a Wiki at his workplace, and a user guide was formed.
This user guide is written by developers;
No resources were assigned to the writing task;
It is written over a very long period of time;
Its accuracy is tested on a daily basis.
It's simply great.

Bribe your Blogger

2007-03-20T00:46:00.000-07:00

I have been a journalist once. As a part of my job I was invited to a product roll-out. Some people were talking, some PR guys put printed text to my hands, asking me to publish it as is, and some other guys fed me with delights I learned to cook by myself ten years later.
It was bribery, fair and square. The journal I worked for had never run for free (although the publisher had never stopped trying to do so, and at the end wend bankruptcy... ). I dodn't work for free, and it was OK to pay me with food in order to make me do things.
This is why blogging is so great. No one pays you (at least not directly) and it is OK to say exactly what you want to say.
Unless... you are paid to blog. Sponsored blog are as OK as official-journals. What I dislike are bloggers who aim at differentiating between journalism and blogging in the account of freedom and unbiased writing.
A "blog" I came across today is writing about the food he was served in a Google Israel event. This is journalism. Period.

The New MyYahoo

2007-03-13T00:49:00.000-07:00

I have subscribed to Yahoo in 1999.
There was a YahooGroup I attended and posting to the group required a subscription. So I subscribed, got a Yahoo email account as well. Later on, I populated my MyYahoo page with things I thought I'll read on a daily basis.
I didn't, so I dropped it.
Years later I subscribed to Gmail. The new email account took over my Yahoo mail account overnight. Today, I am using Google Reader, and blog here. Yahoo? I visit my Yahoo page once in a month, if any.
But I do visit that old Group (now classed under TechGroup) every other day. Why is that group so successful, and why MyYahoo is not?
The answer is, of course, usability.
I return to a website that is useful for me.
Gadgets won't do. Usabilty always does.

WYSIWYG was wrong

2007-03-08T00:41:00.000-08:00

First, there were printed books. Sure, you can buy everything for a dollar or two on paperback, but, for some reason, people prefer a $45 hard copy that weighs a pound or so and hints of the real value of the book.
Then, user manuals did just the same. OK, 20 years ago there was no desktop-printing. but the printhouse could print single-font single-style $1 copies, or go for the good old $45-1lb copies. They ship more expensively, demand more personnel, and the customers get a sense they are getting real value for their money.
WYSIWYG text editors mimicked this approach. Why send a TXT file to your good-old printer if you can send a DOC file to the color-printer over the cubicle? It make you feel you write beeter content, it costs much more and it creates jobs.
I used to work like that myself, I admit. I mimicked book layouts I have never read myself. Then, I switched from Word 2000 / 2003 to RoboHelp X5. Then, I have to move on to a new tool, and the printed layout looked fine, but totally different from whatever I knew before.
The content was readable and accessible. I used up to 10 styles for the entie user guide. Sure, I couldn't create 5 types of bullets and another 4 types of notes.
So what?
The readers could still find what they were looking for and my work became way more simple.
I don't take credit for dropping WYSIWYG. But it dissapeared, and I never missed it.
At that point I started experimenting SocialText for my documentation projects.

What Tacit Knowledge?

2007-02-25T01:47:00.000-08:00

Knowledge Managers say they're after "tacit knowledge" for that matter they have formed "spaces for stories to be told and listened to".
I have always looked at Knowledge Management from the "why would I share knowledge for free" point of view. However, even when I do want to share knowledge, I find out that it isn't so easy.
Saying that I have a story to tell means - I hope - that I know how to get something done. It does not mean that I have a story to tell. Moreover, it does not mean that I am aware to the fact that I have a story to tell.
How would I know that I have tacit knowledge to share?
If it is tacit, I have probably never discussed it with no one. It is not on emails, not on the notes I am writing myself - not explicitly, that's for sure. It is somewhere else and it probably pops-up whenever I need it. Since I don't communicate it, I am not aware to its importance. It fully pops-up up only when I am asked questions like "how do you know this" and "how do you do that".
Well, to expose this tacit knowledge, all the Knowledge Manager has to do is to ask me to carry out some task. But wait, ain't I getting paid for carrying out such tasks in the first place? I am (hopefully...), so I'd replace the previous credo with "... to expose this tacit knowledge, all my manager has to do is to keep asking me to carry out my job".
This way, the job keeps getting done, and no one has to wonder what am I hiding when I reply with "What Tacit Knowledge?".

No more printed documentation

2007-02-21T23:26:00.000-08:00

We're going to lunch. At the dining room there's a little traffic jam by the cash. So I haste to pick a main dish from one of the isles , some carbs from another isle, a salad or two from the salads isles, skip the bread isle and the soup isle and rush to catch us a table. 10 minutes later the guy I am dining with are arriving at the table. "What took you so long?" I stare at the trays that are so similar to mine.
"So many isle and so many variants to choose from". they say.
Lesson #1: don't force people to think and choose. Fascist, but works fine.
At that very day I made our printed documentation obsolete and made my friends stick to On-Line Help only. Sure, it took me two years to fully carry this decision out, but it passed rather easily.
Next: what's wrong with printed documentation?