Switching to Hebrew

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.

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

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

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

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

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

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

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"

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

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

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

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

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?

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

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?