Categories
Business Process Tools Training Uncategorized Writing

Tools of Technical Writing

As technical writing consultants, our job is to advise and recommend. Of course, that advice and those recommendations cover lots of different aspects of the entire process. Obviously, we review the material and try to organize the information so we can present it in the most effective, most efficient way possible. Rarely, if ever, do we receive much push-back from our clients on this part of the process. After all, that’s why they hired us.

 

And while writing and organizing content remains one of the more important parts of our work, we also believe that we have some insight into what tools to use make that efficient presentation of material possible.  Unfortunately, our clients don’t always agree.

Here are some examples.

A company approached us with a problem. It produced a piece of hardware that it sold with optional modules. The company wanted to ship a manual that covered only the modules that were purchased, not all of the modules offered. The problem the company was having was that it had created the manual in Word and either it had to manually manipulate the document each time it made a sale – delete the sections for the modules that weren’t purchased and renumber the chapters and pagination – or send a manual with all of the features and text for all of the modules. Which always creates problems – “Why can’t I get this machine to do what it shows in Chapter 8?” Answer: “Because you didn’t buy the module described in Chapter 8!”

We suggested we import the contents of their manual into FrameMaker and use FrameMaker’s conditional text feature to mark the text that belongs to each module. In this way, we could mark whole chapters that related to individual modules, as well as words and paragraphs – in feature lists, for example, in the introductory sections of the manual – so the resulting document would reflect only those modules that were purchased. A brilliant solution, we thought, and so did the client. Happy client; happy consultant.

A different company talked to us about documenting a large enterprise software package that also offered different, optional modules. After discussing the application with the SMEs and reviewing the existing documentation (our due diligence), we concluded that the final document would be very large – it was a VERY large enterprise software application that did many things – with lots of graphics and screen shots and would not do well in Word. Furthermore, the client admitted that its clients didn’t always buy all of the modules and so would want the ability to offer a manual that only included the modules purchased.

Fresh off the previous consulting engagement in which we were able to address the hardware manufacturer’s similar problem, we proposed using FrameMaker and marking the sections describing each module as conditional text. Then, the company could produce a “customized” document for each of its sales. Not only would we solve the “purchased module” problem, we argued, but we could assure the client that FrameMaker would handle the large size of the document much better than Word because that was what FrameMaker was designed to do and Word was not.

Our contact at the company agreed with us but found little support with her management. Why? Management wanted to be sure it could revise the document without having to hire a FrameMaker “expert” and so wanted it done in Word. What about the optional module problem? “We’ll deal with it internally,” they said. Since in our line of work, the customer is always right, we wrote the manual in Word and regretted every minute we spent on it, knowing the resulting material was inadequate. Alas.

I’ve yet to hear of someone instructing a plumber as to what kind of wrench to use to fix a leaking faucet or tell a carpenter what type of blade to use to cut a piece of wood, or, as I’ve said before, told a developer what language to use to code an application. We hire experts and rely on them to advise and recommend the best way to solve a problem. Technical writers are the experts. Listen to their recommendations.

Categories
Business Flare Process ROI Tools Uncategorized Writing

Lowering the Cost of Documentation

 

Wikipedia defines single sourcing as “a content management method which allows the same source content to be used across different forms of media and more than one time. The labor-intensive and expensive work of editing need only be carried out once, on only one document. This reduces the potential for error, as corrections are only made one time in the source document.” A decent, I think, explanation of what this mysterious approach to documentation is all about.

Categories
Business Process Training Uncategorized Writing

Technical Process Discovery: The Case for a Dedicated Documentation Specialist by Eric Sedor

Without sequencing tasks to a specific purpose, the commonplace actions that constitute office work make little sense and no one would sit around all day doing them, ever. We all recognize the need for processes, but that’s generally where agreement ends.

Categories
Business Marketing Process ROI Tools Uncategorized Writing

RFP Nightmares. Had Enough?

In an earlier article (http://www.shoap.com/rfp-responses-go-technical), we discussed the importance of responding to RFPs with correct, easy to read and understand responses. Several of our readers wondered if there were any tools that could help them address the arduous task of responding to RFPs. This article is for them.

Unquestionably, there are more onerous tasks than responding to a big, fat request for proposal (RFP). Unfortunately, I just can’t think of anything. People who have to do this for a living spend countless (and thankless) hours, ensuring the response is correct and flawless. These responses can go for hundreds of pages, require inputs from various and sundry departments within the organization, and are under tremendous time constraints. It’s stressful just thinking about it. Many companies, however, are facing this nightmare head-on by investing in software that automates the process. Leave the copy/paste method behind.

Categories
Computer Languages VBScript

Using Visual Basic to Automate PowerPoint Printing

For the past three years, I have been trying to find a way to automate the tedious task of printing two copies of 30 plus PowerPoint Presentations to PDF, first as Notes Pages and then as 3 Slides Per Page Handouts.  Every six months I would spend a few hours testing various batch printing applications to see if they would complete this task for me.  Unfortunately, every time I would find they would only print the standard One Slide Per Page view without the Notes field included.