WritePoint Staff Blog

Engineers, programmers, developers; we can;t live with them, we can’t live without them. Dealing with them is part of our jobs, and it can be the worst part at times.

Engineers write some documentation that we use, and even some documentation that the customers may use. A case in point: one company that I worked with would have the engineers write the functional specifications of their products. The writers were not tasked with editing  the documents at all. This brought about a situation where the documents were basically written in “Engineerese”, and since the engineers did not have great English writing skills, the poorly written documents were totally unreadable.

To combat this phenomenon, I’ve prepared a course called Technical Writing for Engineers. This course does not teach them to be technical writers. To be sure, engineers barely have time to complete their own jobs, let alone do ours. This course is a “value-added” seminar. It adds enough value to the engineers’ writing ability to improve the documents that they prepare.

When the engineers can prepare their information in a more readable format, with clearer structure, they will be able to spend more time working on engineering problems, and less time answering questions. We, as technical writers can spend less time puzzling out what they meant to say, and less time hunting them down for explanations, and more time to improve the quality of the documentation.

ezriely Seminars and courses

My friend, Julian Weiss, will be giving a talk at the Fourth Techshoret Conference about agile software. For the non-geeks like me, this means new software that has evolved through teamwork to ensure rapid delivery to the customer. It is the inverse of the established regulated methodology, which is perceived as slow.

In a country like Israel, where growth has become dependent on innovation, agility is a major contributing factor of that commercial evolution. For example, part of the raison d’etre of the country’s successful cleantech industry has been the emphasis on “rush to market”; quickly converting back-of-the-envelope concepts in to actual revenue streams.

The Financial Times newspaper picked up on this same theme in a management blog. Agility, “how well a firm anticipates and responds to environmental changes”, is not purely about IT changes.

Fast decision-making is the engine of agility. A EIU survey found that “rapid decision-making and execution” was the most critical trait of an agile organization, while in a separate question slow decision-making was cited as the biggest obstacle to increasing agility. McKinsey found that “overly centralized, slow, or complex decision-making/approval processes” were cited by 50%  of respondents as the barrier most likely to hamper agility, a factor cited twice as frequently as next most common barrier. Two of the three elements cited as promoting agility in the McKinsey survey also dealt with decision-making., including decision-making authority pushed as far down the organization as possible (cited by 39%) and clearly defined decision-making authority (30%)

The blog goes on to describe the importance of agility; securing improved revenue and stronger employee engagement.

In my view, much of this is obvious. Find a way to be quick, without compromising on quality, and get the completed job out to the customer.

But there’s a big hidden snatch: Many organisations, big or small, come filled with historical internal hindrances. Identifying those issues and resolving them is an important prerequisite to greater flexibility. Creating the conditions agility is a process in itself.

Michael Horesh: michaelhoresh@iib.ws

Michael Horesh business ethics, content management

A few years ago, I went to the funeral of a close friend of the family. In his eulogy, one of the sons of the deceased praised his father: The man always sought to give his best. In business that meant offering a quality service.

“Quality service” A simple phrase, often thrown out blandly. But in the setting of a berievement and self-inspection, it was very penetrating.

I was recently directed to a video click put out on utube by Domino’s Pizza, and fronted by their CEO. You find 2 messages in the four-minute roll. First, they admit that they have been feeding customers tasteless rubbish. Painful, but they admitted it, in public. Second, look out because Domino’s is about to change, big time.

Was this a open lesson in internal conglomerate decision-making? Maybe, but it was also a clever bit of marketing. The company is visibly determined to serve up (literally) a good product.

So what? Well competition is always strong in the pizza market. Even amongst Israel’s 7.5 million holy people, most of the international chains are present. In fact, Domino’s has to try even harder, as most of its stores do not meet kosher eating requirements. And there is a similar named firm, assumedly pinching some goodwill from the name. So the American brand needs to stand out well and good.

Stefan Stern is a syndicated management blogger, who has written about SAS, an American software concern. Fortune magazine described SAS as the best company to work for in 2010. The trick to success is “benign management”. The result?

The 34 year old company had revenues of $2.3bn in 2008, and remains a leading player in the “business intelligence” market.

Simple, isn’t it? No. My wife told me about her troubles with a financial computing package, possibly in the same field as SAS. The upgrade for 2010 came with a built-in bug. The supplier is not informing its customers, as they all blindly pay for the new version. 4 weeks into the new year, and there is no immediate solution in site.

It is not just the problem. Nor even the overtime invested by the good lady. She was played for a fool and that leave’s a lousy, long-lingering taste.

Do you think that she will be looking to buy any add-on products from this global provider of software?

Michael Horesh:  michaelhoresh@iib.ws

Michael Horesh business ethics

As we began another technical writing class, I reviewed the course schedule and contents. In the next few months, this latest group of students will learn Word (2003 and 2007), FrameMaker, RoboHelp, Visio, PowerPoint, Flare, DITA, Social Media, Visio, and so much more. They will learn the proper way to document – from the very start of the documentation project, the outline, through development of a full and comprehensive manual.

One of the modules focuses on peripheral skills they will need – editing, working with graphics, and specifically, working in Israel. This section includes interviewing (engineers, SMEs, etc.) and also being interviewed.

With thanks to Rachel Berger from NBN who sent this link, I hope to use this video in the class. It’s cute and presents a few of those annoying questions some interviewers insist on asking.

admin Uncategorized

I have commented that the Israeli economy ended 2009 in a solid position; absolutely and compared to competitors. So what’s in store for 2010?

I am not a great fan of predictions. But, whether you are an analyst or investor, there are several positive commercial tends to watch out for.

No, I will not concentrate on the stock market or specific companies, here I will look at sectors. Let’s start with tourism. The responsible government ministry is one of the few to receive extra money these days. It has its own new investment centre. It recently launched a plan for 15 new golf courses. And the ministry is seeking to boost hotel space by 5% very rapidly. Ambitious but seemingly relaslistic.

Jerusalem, through the efforts of its mayor, Nir Barkat, intends to be part of that pull on inward tourism. And outside this field, Barkat is looking to expand Jerusalem’s commercial base. He has scrapped a plan to tax high tech profits.

Cleantech will continue to flourish in Israel. February sees the 3rd International Renewable Energy Conference at Eilat. This remote city drew hundreds of participants last year, and the 2010 event is set to be even better. It is a symbol of the advances that Israeli industry has made in exploiting solar and wind energies, as well as other new technologies.

Diplomatic considerations are never far from the mouths of most Israelis. What is generally accepted as one leading reason for Israel’s innovative strength is the large number of high tech graduates, who had previously worked on military projects. In 2010, the IDF has no intention of letting its competitive advantage slip, a good sign for the long term future of the country in general and for the economy specifically.

Finally, I do not want to ignore the retail sector. Quietly in the past decade, Israeli chains have been moving towards overseas markets. Ahava, a manufacturer of Dead Sea cosmetics, has a flag-ship store in London. Castro, adult clothes, has shops in Europe and in the Far East. I am starting to cooperate with a successful franchise line, looking to tackle Europe and America.

Quite a lot for a country of 7.5 million people.

Michael Horesh: mshoresh@netvision.net.il

Michael Horesh Uncategorized

Ever wished there was a more straightforward way of single-sourcing content for multiple outputs? The TemplateMapper plug-in for Adobe FrameMaker may be the tool you’re looking for.

TemplateMapper is not new but has rarely received the attention it deserves as a powerful and yet simple tool for converting between FrameMaker templates. It provides a cheap and easy-to-use alternative for issues such as those related to multiple deliverable types, OEM customization, and conversion of legacy documents.  

Before I continue, a disclaimer: I am in no way affiliated with the vendor or the product. I have, however, used TemplateMapper for developing single-sourced content for multiple outputs without the learning curve or financial outlay of implementing more widely-advertised structured authoring or XML application-based solutions.

I encourage you to compare the functionality and cost of including TemplateMapper in your single-sourcing workflow with other tools and approaches that you currently use or prefer. Feel free to send your comments and feedback to this blog in the light of your own needs and content creation processes.

TemplateMapper is developed by Chris Despopoulos and sold via CudSpan (http://www.cudspan.net/). A single license costs $200 and prices vary depending on the number of licenses purchased. A free evaluation version is available for download for FrameMaker versions 7.x and 8.0. At the time of writing, the latest released version of TemplateMapper is 1.5 which is also suitable for FrameMaker versions 7.x and 8.0.

TemplateMapper enables you to take a suite of legacy FrameMaker books and reproduce the content in an alternate set of templates with completely different formatting for paragraph tags, character tags, conditional tags, table formats, cross-reference formats, you name it. Conversion settings can apply to the following FrameMaker object types:

• Paragraph formats
• Character formats
• Table formats
• Cross-reference formats
• Master pages
• Reference pages
• Condition tags
• Variable names

You can also specify custom plug-ins to perform specified operations on your legacy content before TemplateMapper performs the defined format mapping for that FrameMaker book or file.

So how does Templatemapper work? Let’s take a very simple example using only a single paragraph format. Your real conversions will include at least multiple paragraph and character formats, if not all the FrameMaker objects in your templates. Assume that your legacy files contain a paragraph format called Heading1. You want to convert all instances of Heading1 to a paragraph format in your target files called 1Head.

1. Create a new TemplateMapper map file from File > Utilities > Template Mapper > New Map Document. The map file contains a set of mapping tables for all the FrameMaker object types supported by the plug-in. You define your mapping settings for each object type in the appropriate table.
2. Load your legacy files and target templates to the map file. TemplateMapper displays lists of all the formats present in your legacy files.  The map file contains separate lists for each FrameMaker object type supported (paragraph formats, character formats, table formats, cross-reference formats, master pages, reference pages, variable names, condition tags and preprocess plug-ins).
3. Locate Heading1 in the paragraph format list and click NO_CHANGE to display a list of all the paragraph formats present in your target templates.
4. Select 1Head and save the map file.
5. Access the TemplateMapper Job Control panel from File > Utilities > Template Mapper > Job Control Panel.  The Job Control panel is where you define legacy file-to-target template mappings, and specify which of the supported object types you want to include in the conversion.



6. Load your legacy files, target templates, and the map file to the Job Control panel.
7. Select the FrameMaker object type formats that you want to convert (paragraph formats only in our simplified example).
8. Define the swap action and the template to associate with each of your legacy files, and click Run Job.

TemplateMapper converts the contents of each file to the target formatting according to the pairs listed in each mapping table row in the map file.  The entire conversion process is summarized in the diagram. 

So what do you think? Could TemplateMapper enhance your single-sourced workflow? Get blogging!

Andy Lewis DITA, content management, single sourcing, technical writing Adobe, content management, content reuse, DITA, economy, FrameMaker, single sourcing, structured writing, technical communications, technical writing, XML

Thomas Wolfe wrote “You can’t go home again”.

Not quite true. I’ve come home. To WritePoint.

I first joined WritePoint way back in the old days, and due to “circumstances beyond my control”, I moved into in-house positions. Interesting work, I might add, but at times, a bit stifling. There are time when writing another application note or editing another PowerPoint presentation is just too much. There were times when I was sure that my skills and strengths were not being used to their maximum potential.

Jump ahead to today, and I see how much WritePoint has grown. The company, as I remember it, worked out of Paula Stern’s basement in Ma’ale Adumim back then. Courses were offered whenever a suitable conference room could be rented for a couple of days. And the Techchoret Communicator’s Conference was merely a glimmer of an idea in Paula’s mind.

When I spoke with Paula, and told her that I wanted to come home to WritePoint, I think that she was rather touched by it nthe request. And of course, over a 15-minute conversation, we managed to created a position that made proper use of my skills and strengths. I can write fairly well, I can teach (2-3 hours a week for the  past seven years), and I can help other writers.

Being Director of Training is a great opportunity for me. Not only will I be doing the standard technical writing stuff, I will also be managing projects and teaching. It just so happens that my experience and background in writing is exactly what WritePoint needs taught.

As a blurb for the new position,  allow me to say that there are some interesting courses coming up over the next few months. The role of the technical writer is becoming a cross between a technical communicator and an information manager. We are developing courses and ideas to help people transition into the new challenges that this field has to offer.

So it seems that I have defied the common folk saying. I (at least) CAN go home again.

ezriely Uncategorized

As you probably remember, in November 2009, we conducted a survey to measure and document the issues that technical communicators experience when using DITA. We want to thank everyone who participated in the survey and helped us gather this invaluable information.

We believe that the results of the survey are interesting both to those teams that are already using DITA and to those who are looking to DITA as a possible solution.

The report that summarizes your answers is available now. You can download the full report (PDF) from http://www.writepoint.com/site/downloads/WritePoint_DITASurveyChallenges_Results.pdf.

We will be happy to get your comments and suggestions regarding this survey here in the blog. Also, please feel free to let us know about any other survey that you would like to see in the future.

Again, thank you and we’ll be looking forward to your feedback!

Alex Masycheff DITA, content management, single sourcing, technical writing CMS, content management, content management system, content reuse, DITA, DITA tools, single sourcing, survey, technical writing, XML

We all realize the value that content reuse, flexible content customization, multichannel publishing, and consistency can add to the documentation process.

Darwin Information Typing Architecture (DITA) provides a framework for achieving these goals. However, DITA also introduces new challenges. One of them is the ability to manage your content effectively. It’s one thing when you write in a traditional document-oriented way and keep track of 5 monolithic documents, but it’s a completely different issue when you write in DITA and have to maintain thousands of individual stand-alone topics.

This is when you might need a content management system (CMS). You can get the real benefit when your CMS is integrated with your authoring tool. This way, you can manage your DITA content without leaving the authoring environment.
In the winter issue of Communicator (this is the quarterly journal published by the Institute of Sdcientific and Technical Communicators, http://www.istc.org.uk/Publications/communicator.htm), Andy Lewis and myself wrote about integration of DITA-aware CMSs with Adobe FrameMaker.

For the full article, click here.

Alex Masycheff DITA, content management, single sourcing, software CMS, content management, content management system, content reuse, DITA, DITA tools, FrameMaker, single sourcing, technical writing, XML

You can call me lazy, but I prefer solving any problems without leaving the office. This could be a situation where I am in one city, and need to discuss important issues with co-workers or clients in another city.

It can equally apply to people in a different department, a different floor, or a different building.

In many ways, personal contact is still required in work relationships. However, personal contact comes at the expense of time and efficiency. If you spend more time stuck in a traffic jam than actually solving the problem at the client’s site, then a new way of working and communicating must be found.

Today’s post is about a tool called TeamViewer.

As a disclaimer, I want to emphasize that I’m not affiliated in any way with the vendor. I’m just telling you what I like and why. I welcome your feedback and ideas about other applications and solutions that you are using and would recommend.

TeamViewer allows you access to remote computers, share desktops, run presentations, transfer files, and do many other useful things that can make physical travel to a customer’s site unnecessary.

This is how it works:

1. You install TeamViewer on your computer. Your client starts a small module (which does not even require installation) on their computer. This module automatically generates an ID and a password that the client gives to you. This allows you to connect to their computer.

2. You start TeamViewer on your computer and enter the ID and password that you received from the client. You then choose what you want to do: take control of the client’s computer, show a PowerPoint presentation, transfer a file, or set up a virtual private network (VPN).

As you can see on the screenshot, TeamViewer also generates an ID and a password for you. This allows you to give your client access to your computer as well.

At this point, you can take control over the remote computer and do whatever you do on your own computer: browse files, run applications, open files, edit documents, and so on. A remote computer responds with a little delay, but usually you almost don’t notice it.

I use this application a lot with clients for whom we’ve implemented content management solutions to check out problems directly on their computers (for example, to make sure that the tools on their machines are configured correctly and files are properly organized). It also helps when a client reports an issue that I can’t reproduce on my system. I can reproduce the issue and investigate the settings directly on the client’s computer.

Another very useful feature is the ability to show PowerPoint presentations. You can’t do it for a group of people as you can do it with WebEx or other similar services, but if you need just to show your presentation to your client, partner, or co-worker and don’t want to pay for it – this is be an ideal choice.

What I personally like is whiteboard. When I am training teams at our clients’ premises, I always ask to put a whiteboard into the training room. If you are like me, and like to draw when explaining something, you’ll definitely find it useful too. Pick up a tool you need – marker, callout, text, rectangular, etc. – put it on the working area, and your partner will see what you wanted to highlight.

You can even chat via text during the presentation. The application does not currently support a Voice over IP channel, so you still need a telephone line, or an external application to conduct voice chats.

Finally, you can setup a virtual private network (VPN) and access a remote computer using Windows Explorer like any other computer in your local network.

Now you are probably asking yourself what this costs. The good news is that if you are using TeamViewer for non-commercial purposes, it’s free. When you close the connection to a remote computer, the program displays a nag screen saying that the session was sponsored by www.teamviewer.com and reminding you that free sessions are available for non-commercial use
only.

Business licenses start $749. You can find all pricing information at http://www.teamviewer.com/licensing/index.aspx.

All in all, I believe this is an amazing product for one-to-one sessions. There are a few small bugs in the messages, like a politically incorrect “you can connect your partner via his IP”, or grammatically wrong “this are two possibilities”, but they don’t make the product any less attractive. When I think about the time that I saved thanks to this product, I would excuse developers for this oversight.

Alex Masycheff collaboration, free applications team collaboration