Technical Writer

On Rescuing Lord Dunsany's Guerrilla from My Discard Pile

When the knackerman for books arrives in the guise of one of the uniformed recycling truck crew this Friday, I will have a few hundred books to discard.  Why do I need to keep two paperback copies of Matilda, when I have a nice hardcover?  Two paperback copies each of various C.S.Lewis science fiction titles that I also have in hardcover, an extra copy of St. Augustine's Confessions--you get the drift.  It is nearly impossible for me to discard books, but I am biting the bullet and throwing many away.  The shelves are looking better already and I feel free of acid-burned paper.

I surveyed the rejects in the basement last night and recognized that in my zest for rejuvenating the stacks some worthy books were lost in the shuffle.  I retrieved Edward Dunsany's Guerrilla, and just finished rereading just before it was time to get out of bed this morning. Mine is a fine old copy, published in 1944, in cloth cover with a library binding.  This particular book was discarded from a New England town library many years ago. 

The publication date is interesting, because this is a story about resistance fighters in an unnamed Land in World War Two, at a time when the outcome of the war was not known.  To Dunsany, however, the truth of the outcome of the war could be known because Liberty as he wrote of it is as hard as the rock of the mountains that gave their strength to a free people and could not be effaced.

I read the book as a gorgeous, long, discursive essay on beauty and time and human integrity bound to the land.  There is also information about terrain of mountains and of people themselves, and quite a bit on hiding in plain sight from the attacking Stukas above and infantry below.

As Dunsany wrote in his Foreword,

The man who told this tale had got to London, after sufferings of which he never spoke. He was full of hope, a hope so firm that it induced in him almost a kind of gaiety, and certainly a fine energy. He was an uncle of the lad of whom the story chiefly tells. And the story went something like this: without details, with few names of persons or places, nor even the name of the country. Something had taught him to mention names rarely, and to believe that German ears were always listening, even in London.

But it is not the names or the places or the lesser details that are important. And I cannot be sure enough that this violent story of mine of this little fraction of the rage of a furious year will last to be read in the calm days that shall come after our war, for me to describe with any more exactitude this story, magnificent in its spirit and hope and courage.

I commend this book to you, and here is a link to Project Gutenberg, which offers the book text online.

http://www.gutenberg.ca/ebooks/dunsany-guerrilla/dunsany-guerrilla-00-h.html

Home-Made WiFi-Sniffing Drone a Viral Smash Hit

Everyone is a critic.  After Mike and Rich spent about 5 months building a fine little machine in their garages, painted it yellow and even topped it with googly eyes that signal friendly interest and harmless intent, they paid their entry fees and took that little baby out for a spin to Las Vegas for the annual DefCon gathering a couple of weeks ago. Suddenly, the lads and their 13-pound, 76-inch long drone named WASP (WiFi Aerial Surveillance Platform), all three full to bursting with capabilities, are media magnets. Look at their WASP site and click the links they've added to media coverage. 

What's not to like?  Wouldn't you want to know that a couple of bright fellows in their off time have built a machine that can swoop in and grab your data and spot its (and your) movements? Wouldn't you want to know if your data is not safe?  We should prefer that our vulnerabilities are exposed by our friends, and in fact, this is a social feature found in communities of top predators. 

Instead of relying on those outside the pack to take us down, let's spar and jab, probe and develop, as training to remain on top.  If we have freedom to think and act independently, then all the benefits of outlier thinking  and behavior remain available to us, and we need this critically in a government, military and business environment that in our culture is trimmed to the bottom line.

There are naysayers.  Instead of celebrating human accomplishment and especially blind to the significant good fortune that Mike and Rich, both United States citizens, are on the side of freedom and security, an English aeromodelers' association asserts, "What they hope to get out of this project is not known. " 

Further, the aeromodelers' association continues,

"Loss of freedoms for traditional aeromodellers is already on the cards as authorities around the world realise what the largely ignored group is now capable of. ...  Actions of groups that claim to be defending freedoms or rights might lead to less for more."  

Are the aeromodelers making a case for the evils of overreaching?  The opposite is true and further, our friends in relevant industries and at DARPA need to be alert to the WASP’s potential and what it represents.  By now, I am certain they are.

White Hat Nak Muay

The world is full of highly skilled and focused cybersecurity geeks, and not all are on our side. Most of them live in countries (and states) where the national sport appears to be hacking into our corporate and government systems, and while these systems are usually electronic, the target systems may be the biochemical configurations of individuals or even societies formed by human relationships.  If an entity is programmed, whether the code is genetic, social, or electronic, the hacker finds work to do. 

Hackers' World

He told me years ago that the programmers had whipped up a little something that enabled them to view the Internet traffic of some bad guys in Columbia and elsewhere in South America. What did you see? I asked. It turns out there is a reason why all the great scandals of history devolve to either money or sex.  When you track the dopes who run cartels you are fogging for the cyber prints of vicious and narrowly focused creeps whose ideas of winning or getting ahead have to do with subjugation of bodies, literally or financially.  The Web traffic? It's mostly about their personal peccadilloes of the coarsest nature. 

When was the last time you read about a scandal concerning aesthetic judgment?  If Christie's and Sotheby's are in the news, it is because there is collusion in the art world, or someone sent a fake to market.  Where is news of art that influences perception?  Where is the philosophy that bends of the curve of conventional thinking?  I do look for it.

I would enjoy reading an above-the-fold article in The New York Times about Nicholas Kiersey's and Doug Stokes's new book coming in September, Foucault and International Relations: New Critical Engagements (Interventions), from Routledge.  At $113 through Amazon, it looks promising, if you are searching for the application of biopolitics in the War on Terror.  I will quote Amazon on the book. http://www.amazon.com/Foucault-International-Relations-Engagements-Interventions/dp/041557983X

    "The recent debate about biopolitics in International Relations (IR) theory may well prove to be one of  the most provocative and rewarding engagements with the concept of power in the history of the discipline. Building on Foucault's arguments concerning the role played by the concept of security in 19th-century liberal government, numerous IR scholars are now arguing for the relevance of his theories of biopolitics and governmentality for understanding the Global War on Terror (GWOT) and broader issues of security and governance in the post 9/11 world.

    "Conversely, others have criticized this idea. Marxist and Communitarian scholars have challenged the notion that the category of biopolitics can be 'scaled' up to the level of international relations with any analytical precision. This edited volume covers these debates in IR with a series of critical engagements with Foucault's own thought and its increasing relevance for understanding international relations in the post 9/11 world."

Go boys!

I plan to order ahead because I want to understand the framework of a better concept of security than we have now.  The framework our thought leaders are developing will enable our other lights to fashion the tools we need to remain a free and expansive society.  One result of failure to think ahead for the good of all is further polarization of our country. The second and concomitant failure is the increased actualization of risks so seemingly far-fetched that even a responsible business or government decides it can not mitigate without overwhelming the cost of running the joint.

If we do not think ahead and act for the good of the whole, our ability to act collectively for the good of all becomes overwhelmed by persistent degradations. It's circular, and true, and the dopes only think they win. They lose, as do we all.

Boy on a Broken Bike This Morning

I have discovered a peppy music site for kids.  Click on BostonPete.com and find your way to the Child's Play tuner, and listen to great kid hits such as Here We Go Loopy Lou, which I am listening to at this very moment.  Before that?  A peppy version of Achy-Breaky Heart, which I would not have guessed would  appeal to the kindergarten-middle school set, but apparently I am wrong.  Before that, there was a rousing version of YMCA, which for the first time I have now heard in its entirety.  What a swell song.  When I was a kid, my little sisters and I used to love to sing Puff the Magic Dragon, which galled our Mother for reasons we knew not, but which drove us to sing it day and night. 

I've figured out that pep is the leavening for kids' music, and often a little education is added to the lyrics, such as in a song about what to do when you are lost.  If you are lost at the mall, go inside a store and tell the clerk that you are lost.  If you are at the carnival, find a family with children and tell the mother that you are lost. The mom will know just what to do and you will be safe. That's the content of a zippy little song, and it is great. 

On my way to the office this morning as I was pulling out of the driveway by my house, there was a little boy of middle school age, and he was trying to fix his bike by the side of the road.  A piece had broken away from the frame.  He pushed the piece back where it belonged, hopped on and rode 10 feet, when the metal piece jammed against his pedal, and he got off again. I pulled over, got out, and talked to young Leith, for such is his name. I asked him if he would like to call his mom or dad with my phone, but his parents, he said, were out of town. 

It was also unusual that this child was a couple of blocks in the wrong direction (on E. 4th St.) between his 2nd St. house and West Frederick Middle School, but I didn't ask about that. I asked him if he wanted a ride to school.  After some calm talk, we put the bike in the trunk of the car, and with the trunk wide open, hazard lights flashing, and the youngster safely in the passenger seat, off we went to school. I noticed a police officer on a Segway was about to cross Patrick St. about a block from the school, and the officer noticed me.  I felt some gratitude that there was an observant policeman near the school and I wonder how many parents are aware that their kids are watched carefully by the official protectors.

We arrived at school, Leith put his bike in the bike rack and went inside, and I departed.   It is a little tricky offering help to a child in need of it but who isn't actually lost.  I approached the child, and hoped that my plainness might signal safety to him, even though his parents have probably told him to be wary of all strangers.  When I arrived at my office, I called the counselor's office to request that someone check on the boy and maybe fix his bike so that on his way home he wouldn't have the same trouble and run across another stranger who might offer him a lift home.

Would we all had someone looking out for us.  Wait--Carole King's You've Got a Friend just came on, no kidding.  I'll end this post and listen.

They Deserve Better

I have BostonPete.com in my ear at the moment, tuned to songs for children, or at least the child in me.  It is not having the desired effect, which is to calm me after reviewing today's news on the oil leak in the Gulf.  I can't help but feel a little sickened by the image I'm trying to distract myself from--a shore bird covered with a glop of oil, and the bird is still alive, and the camera has focused on the bird's eye.    

I am more affected by an injured animal than I am by suffering humanity, but even writing this, I know it to be not wholly true.  Last summer on the coast of Maine, I stopped on my early morning walk to take a picture of a humble fisherman in Waldoboro.  In grime and stench and obvious poverty, he was sorting his rotting bait mackerel in the barrels by his beat-up Ford 250. When I called out hello, the fellow turned and smiled. I was stopped in my tracks because I was looking suddenly at a decent fellow trying to make a living in the muck. We spoke a awhile, and he let me take his picture, which I could never post.   

He reminded me of a stranger I saw when I was a kid shopping for my mother at the Safeway on 7th St.  I had just wrestled a shopping cart loose from the rack when a large man in a bill cap and red and black checked shirt that was too small across his belly rushed into the store and I could tell that he was simple.  He held in his hand a fan of dollar bills and he had such a sweet and hopeful expression on his face that I have never forgotten him, and I have always wished him well.

Paul wrote, "For we know that the whole creation groaneth and travaileth in pain together until now," but I know the "until now" part will go on and on unto the last syllable of recorded time, when fools are no longer foolish, and there is some mercy in life, which I do not understand.

Its need shows in the long stares of the fishermen on the Gulf coast today, and in the gaze of a shore bird.

Term Papers Are Coming Due, Students Beware

When I was a stupid kid, I wrote papers for the jocks at Frederick Community College who needed to pass their classes to stay on their teams.  I grew up, turned 18, discerned the error of my ways after being nabbed, nearly, taking someone else's final exam at the University of Maryland. The teaching assistant was too blinded by my flashing smile to gleam that I wasn't his student until the exam was lost in the pile in front of him. I high-tailed it out of Ellicott Hall and halted that line of business, but that foolish (at best) period in my life has left me with a skill.  I am able to discern when words not their own have been put on paper by the students of the Professor who married me (despite my confession to him of that bad monkey enterprise).

It's not always the text itself that gives them away.  I'll not forget the paper (such a delight to read) that turned out to have been a piece unchanged by a single word of a several years-old issue of The Economist, complete with poached footnotes. I downloaded the article and stapled it to the term paper, and the Professor returned it with neither grade nor comment to Missy, for such was her name. What gave Missy away?  Her signature on the cover sheet was crowned with hearts over the i's of her name.  The text?  Clear and concise, well organized, and probably peer reviewed, which I suspected was beyond the ken of the young student. The Professor gave the kid another chance. I married a good man.

Process Improvements for Those in the Knot Know

Alexander the Great got it right when he took the sharp edge of his blade to the Gordian Knot.  Sometimes it takes a fresh eye to solve an intractable tangle. Recognize that Alexander's strong arm could have been any extension of his will and intellect, but also that he was a warrior trained to succeed.

I thought of Alexander as I admired on the front page of The New York Times this morning an image of a PowerPoint slide that purports to represent the complexity of the path to peace in Afghanistan.
Now this is a knot worthy of vanquishing.  Here is the article link, 

http://www.nytimes.com/2010/04/27/world/27powerpoint.html?hp

and it is worth reading if you are a technical writer, although it was written not for us, but instead as an examination of how the limits of a software application impede free thinking and decisive action.  The article is about warfare, and the dull-headed representation of it in military briefings these days.  I write not really knowing this, but I can look at this slide and wonder what the heck, too.  Out there is a bright young Ender just waiting for her moment in the game, and she knows all about cutting the Gordian Knot.

The League of Red-Headed Men

The assignment was obviously temporary, but my friend was happy to accept a well-paid job for a far-away company that is riding out the tail end of a contract.  All around her are the sounds of staff adrift in their own boats:  Here an animated conversation between software engineers about their gaming avatars (the take away: even a sorcerer must travel with a healer) and there the keyboard clicking of industrious engineers composing websites for friends.  Other staff have been using 6 to 7 hours daily to search for new employment.  The problem?

The contract will not be renewed. There is, however, the inflow of income to the company by keeping positions filled on this contract for its few remaining months.  How does a tech writer fill such days that were not promoted as devoid of professional work beyond the initial swirl of a few technical white papers? 

One decides that one has been handed an exciting fellowship to spend three months in totally independent, well-supported learning.  There is CSS to learn cold, and Java scripting.  Why would one ever use a design software when there is a world of information on directly writing Web pages that if learned well is far more useful?  Lucky person.

Sweet But Boring Technical Writer

To inflict myself with guilt and observe how my inattention to this blog for the last year has affected my readership, I take a quick peek at statistics now and again to confirm that readers are still interested in my site.  If it weren't for my single article on Duncraig announcing its sale a year ago, no one except my one reader would ever turn to its pages.  Oddly, my average readership has remained unchanged, due to the Duncraig search that returns my page to the head of the results for "duncraig castle for sale."  

Noticing recently that someone had found a different location on my site through Google, I clicked on the link to the search results page to discover these sad little search words: "sweet but boring technical writer."  Lo! What site should appear at the top but mine!  How have I sunk so low?  I know that Google was not making a value statement, but perhaps I ought to take the hint and part my hair on the side, not down the center, for awhile.  Maybe a new white blouse. Damn.

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.