Technical Writer

Saturday Flowers #7

The single stem of dark red yarrow is in the bouquet for drama. 

The front-page, above-the-fold photographs of The New York Times are frequently works of art in composition and meaningful expression, but today the Journal trumps the Times.

I must admit, however, that I am enjoying the Journal less and less these days.

A few minutes ago, my brother-in-law called to ask me to recommend a few books on grammar and language for his student daughter.  I turned my gaze to my nearby shelf of language books and my first recommendation was Strunk and White's The Elements of Style.  In my opinion, this is the quintessential English language reference book.  You may get yourself a used copy for a couple of dollars and have a handy paperback that explains the elementary rules of usage such as

"1. Form the possessive singular of nouns by adding 's.  Follow this rule whatever the final consonant.  Thus write,

Charles's friend

Burns's poems

the witch's malice"

(Notice that the authors neither begin the phrase the witch's malice with a capital t nor end the final example with a period. One learns so much more than what is expressly stated.) 

Read this book for an excellent grounding in sensible expression and use that will hold you steady in any linguistic head wind, and then trim your sails as need arises with any of the other manuals of style, such as The Associated Press Stylebook, or the MLS guide, and my favorite, The Chicago Manual of Style.With the precepts of Strunk and White clear in mind, you may learn the alternative styles that have developed for the print media, for different schools of academic use, for government and business, and recognize them as variations.

Converting a Doc from Publisher to Word

Earlier this year I sent a client a long document that I had written and cleverly and elegantly designed in Microsoft Publisher.  Publisher has features that make production of documents a pleasure, and it has been my design software for many years. When my client asked me for a Microsoft Word version of the document, I knew I was in for a conversion slog. Conversion is too simple a statement. I had to make a new document that was identical to the old, without the ease I had hoped between the programs.  The task was such a bear that I may never use Publisher again when working in Microsoft, unless the client is skilled in Publisher and specifically requests its use. 

Op-Ed New York Times 10.17 Brilliant

I spent a joyful few minutes this morning with several cups of Typhoo tea and reading the Op-Ed page of The New York Times.  Page A27 was the perfect conjunction of my favorite commentators--David Brooks, Paul Krugman, and Warren Buffett and reading them was like being in the presence of friends gathering to review the events that matter. Brooks wrote that candidates such as Barack Obama strive to fulfill some capacity in their nature rather than seeking to fill a void as does the current president; Nobel prize winner Krugman wrote that the next president should spend money up front to improve the country's future; and finally Buffett wrote that he is buying American stocks now because if you wait for the robins spring will be over. 

 

What could I offer, I thought, to contribute to intellectual discourse at the kitchen table this morning?  I have small pieces left on the cutting room floor today from a larger article for a client.  I have written before here about my business of technical writing, and today's leftover piece is on the commoditization in the IT industry. My three readers and the few readers in India I have somehow attracted could care less, however, and I have to agree.  Somehow the subject is yesterday's news.

 

 

Technical Writer Onshore in an Offshore World

"How do you make hay while the sun shines?"

Believing as I do that good tech writing can be found where there is ability and ambition supported by good communications infrastructure, I know that knowledge workers (and tech writers are surely that) are found nearly everywhere on the globe. Why should a company pay more for tech writing from Location 1 when the same product can be bought for a great deal less at Location 2? 

This is a problem that needs to be solved for any company considering moving to an offshore cost center to scale back, way back, the expense of producing technical documentation. I call this a problem, rather than a challenge because rather than the latter's faintly pugilistic tone, a forthright problem requires the active engagement of minds to come to a good solution. (I have a friend who believed she needed to expunge the word problem from her business vocabulary and use instead the word challenge, because it seemed that a challenge was positive, but a problem was negative. Nonsense. I may challenge you to solve a problem, but if I challenge you to resolve a challenge you could be staring down the wrong end of a barrel.)

To take technical documentation offshore requires careful management.  The company must define exact goals, and then adapt and continually monitor strategy taking into account matters of expectation and culture, and ownership of the result. A big feedback loop must be constructed up front, and always monitored because intercontinental business relationships are taken for granted at a company's peril.

There remains the problem of the technical writers left behind.  There are ways to resolve this for the benefit of the company and writers alike, and this takes maturity and thoughtful judgment.

Technical Writing as a Commodity

I was confronted by a concept recently that had not occurred to me before, and that is the commoditization of software and the delivery of IT services. What commoditization means is that as software companies leapfrog each other in design and delivery of products, the real difference to a customer is simply that competing products may over time become similar enough that price drives the purchase. For example, do I really need to understand the difference between one or another security software that guards my PC? I do not.  In choosing one over other options for security for example, I choose what is convenient to download from products within an acceptable price range.

Understanding the concept of commoditization has reframed for me the corporate strategy to outsource technical writing to the lowest bidder who upfront will assert that requirements will be met. This baseline documentation is not valuable to a company; it is simply the accompanying necessary evil all users grumble about. The plain fact is that no client pays extra for basic technical documentation of a product, so why would a company pour resources into delivering finely detailed documentation? Value is added when clients pay for customization of documentation, which in my experience then stays in the United States when the software has been developed here.

Transitions are rarely pleasant, and I have erased the rest of this sentence too many times to write more.

I am including a comment here from a reader and my response to it because I think it is an important part of the conversation.

Reader's Post: What challenges does this present to you as a consultant?

For consultants, the transition is loaded with opportunity due to the need for high-quality technical documentation.

I imagine that really useful documentation is not high on the list of a software buyer's requirements, but surely one measure of the utility of a software product is documentation support for users.

Scenario A:  I have tech writer friends who work for a company where documentation is highly regarded as an element of software packages by the corporation. Good doc is part of the corporation's competitive edge. I would like to believe that in the sales pitch, Salesperson explains to Buyer,

"The cost of our package includes such stunningly great, always tested, and evolving documentation that your future costs for training and maintenance will be 20 percent less than if you buy Product X, Y, or Z. Here, let me show you how."

I would pay money to see such a demonstration because as a client, it would teach me something useful.

There is opportunity for consultants in Scenario A because good documentation matters. In fact, I do work for such a company as a consultant.

Then there is the other side of the picture, at another company.

Scenario B:  I have tech writer friends who work for a company where documentation is not highly regarded. In this case, the corporate position is closer to,

"Here is the product--notice the drop down windows of user documentation--many are correct! We offer pricey customized training guides and reference materials that will give you the tools you need to make the work force skilled in using our product."

Much of the difference between the two companies is the degree of respect for the total product, and respect for the customer.  I imagine that the Scenario B corporation is closer to commoditization of its product than the first company I describe.

As a consultant, my opportunity in Scenario B comes by contracting directly with the customers.  There is a bigger opportunity, and I will discuss that next.

Snarky Technical Writers

My friends are snarky tech writers. I must amend my statement.  While many of my friends are technical writers, all of whom are snarky, I do have other friends, and they are snarky, too. The smarter the snarkier. They have other qualities, but they delight in deploying witty one-liners aimed directly at my virtuous efforts to uplift common humanity with my edifying point of view. In other words, all I am trying to do with this blog is class up the joint with my literary aspirations. My pals (a loose term) are so very much more comfortable slapping their sides silly at their own humor and belching and reading The Onion, sometimes on company time I might point out. (theonion.com)

What Does a Tech Writer Write?

I've decided not to write about my profession, unless of course, begged to by an adoring fan--just one would do.