Categories
Language Training Writing

Creativity in Technical Writing

By Rachel Shoap

To many people, just hearing the words “technical writing” evokes feelings of fear but mostly boredom. “What kind of person can tediously and meticulously write all day long while simultaneously lacking even an inkling of creativity and originality? I could never.” So said my technically (untrained) mind. Whenever I wrote in high school or college, my papers were riddled with profound metaphors and dialogue that formulated beautiful stories and character development that I was proud of. How could anyone choose to write technical manuals? They’re so bland! How could they knowingly choose a topic and style of writing that prohibits that creative flare that most of humanity longs for?

What exactly do technical writers do? For the most part, they put together information, precisely explain the significance of it, take the reader through the necessary steps to complete a task, and disseminate it to the masses in a way the masses can understand. This got me thinking. In its own right, technical writing has to be relatable and at the same time diverse. A technical writer has to strategically relay information while considering the mindset of the consumers of that information, as well as their ability to follow directions.

My ability to understand and dissect information presented to me may be completely different than Barbara’s, the 72-year-old grandma whose grandkids bought her a new cellphone for Christmas. Technical writers are tasked with making sure the information that they provide to consumers is relatable while making sure it is accurate and easy to follow.

Making something “easy to understand” truly takes inventiveness to another level. The ability to take this most technical information and make it understandable for people from different backgrounds, educational levels, and ages calls for the most creative of writers, even if writers that meet the social standard of creativeness do not think so.

Categories
Business Flare Process Tools Training Uncategorized Writing

When the Best Solution Is Not the Right Solution

If, after examining and analyzing a problem, I find the best solution, I recommend and, at times, fight for that solution. This approach seems so self-evidently correct that I’m shocked to find myself even writing it.

Categories
Business Process Tools Training Uncategorized Writing

Technical Editing

T.S. Eliot dedicated the “The Waste Land,” arguably one of the most important poems written in the 20th century, to Ezra Pound for his timely edits. According to Richard Ellman, Pound persuaded Eliot to remove several poems that Eliot had inserted between the stanzas of “The Waste Land.” As Pound said, “the longest poem in the English langwidge [sic]. Don’t try to bust all records by prolonging it three pages further.” (From “The First Waste Land.” In Eliot in His Time: Essays on the Occasion of the Fiftieth Anniversary of The Waste Land.” Princeton, Princeton UP, 1973.)

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 Process Training Uncategorized Useful Links Writing

Technical Writing: Clarity and Precision

Good writing is clear and precise. Good technical writing, to borrow a phrase from the young people, is totally clear and precise. Let’s be real: most people don’t bother reading technical documentation until they’re stuck and don’t know how to proceed. Enter this? Press that? “What do I do now?” Unfortunately for those sorry folks, their foray into the user manual or online help is often not a good experience. The reason: the explanation is not clear and/or precise. Such is the state of my chosen profession.

Categories
Business Marketing Process Uncategorized Writing

Technical Writers as Subject Matter Experts

According to Wikipedia, a subject matter expert (SME) is a person “who is an authority in a particular area or topic.” When a company engages a technical writer, in addition to working with the actual product he or she is documenting, the writer must rely on the SME as the source of all knowledge, the one person who can explain how the system works and, perhaps more importantly, why it works that way.

Categories
Business Marketing Process Rants ROI Training Uncategorized Writing

How to Improve Documentation

Recently, a prospect called us about a training guide he needed written for a new enterprise application his company had recently purchased and was trying to implement. Unfortunately, he had already paid the company that developed the application to create training materials but found, once he had a chance to review the materials, that they were not only impenetrable and useless from a user’s point of view but mostly incorrect as well. A complete waste of money. Alas.

Categories
Business Process Uncategorized Writing

Can Cartography Teach Us About Documentation Design?

Objectivity tends to be one of the core values of technical fields. The fundamental laws of physics dictate the properties of microprocessors, and chemistry defines the properties of the materials we use. These methods make up the API, determining how that application behaves and what it is capable of doing. The way that people interact with technology, however, is anything but objective. They bring a lifetime’s worth of experiences that guide their behavior and frame their expectations for both what the technology will do for them and how it will perform its duty.

Categories
Business Computer Languages Language Process Tools Uncategorized Writing

Technical Writing for the Cloud

Technical Writing for the Cloud

By: Eric Sedor
Eric Sedor, a frequent contributor to the Shoap Technical Reader, is a senior software engineer at MongoLab, a cloud-based database provider located in San Francisco. Eric cut his technical writing teeth at Shoap Technical Services before returning to his true passion, software engineering.

The Cloud encapsulates the idea of a distributed system built of formable, destructible, re-creatable components. Even the data within cloud systems is redundant and spread out, capable of being restored in parts to specific points in time, if necessary. Cloud systems even overlap one another.

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.