Docs Ready for Tech Review?

Show MarkupPenny Orwick and I completed a series of posts for Steyer Associates on peer reviews for technical documentation.

A point we both made in our example peer reviews was that the original draft content wasn’t ready for review, much less for publication. To wrap up our series, Penny suggested a checklist.

Today’s Ready for Review? A Checklist provides the basics, plus some cautionary notes about what you risk losing if you send poor docs for tech review:

  • Discrediting yourself with your technical experts
  • Discrediting yourself with your peers

Typically I link to my tech-communications blog topic with a parallel for fiction writers. But it seems like there are a lot of models out there. So this time I’ll just link again to my Checklist for Writer/Editor Collaborations.

Other topics in our “peer review tips” collection:

 

“What If They Fire My Boss?”

AbideThis article is for my peers and comrades who are technical-communications professionals that work in vendor contracting agencies, rather than working as full-time employees of a technology company.

Here in Seattle right now, you can’t innocently browse the Web, glance at your Facebook feed, or check scores in the local newspaper without a fearsome speculation jumping out to grab you:

“Layoffs of up to 5,642 Reportedly Expected”
“With Merger, Local Layoffs Are Expected”
“Will Wall Street Still Love this Company When It Lays Off 20% of  Workforce?”

Then your mother or sister or best friend from college calls and asks, innocently, “Will you lose your job with all these layoffs?”

… that haven’t actually happened …

Those of us who choose to work as contract employees are always steeped in uncertainty:

What happens if this contract is cancelled?

Will this contract be renewed when it ends?

Have all contracting jobs dried up?

Let me share some manager’s experience about the issues that can affect contract works when the “permanent” supervisor’s position seems to be in jeopardy. Continue reading

Curious Incident of the Cuckoo in the…

Irresistibly curious, I’m reading The Cuckoo’s Calling–not so that you don’t have to, because it’s actually a good British detective mystery (of which I’m a fan).

The only criticism I’d make is that the first 25 pages would not have made it over the transom in a U.S. publishing company, but from there, the book is more than just a little bit good. The psychologizing of characters is quite good–not as good as Denise Mina, but there might be a potential for the writer to get that good over time.

I’m just about to hit the mid-point plot twist (can’t hardly wait!), but paused when a new clue appeared: the sister-in-law of an attorney revealed confidential information learned from his family-law practice. Galbraith/Rowling has his/her own personal series of unfortunate coincidences–this time, fiction foreshadowed life.

Also, the publisher did a good job on the ebook formatting, and is not charging hardbound prices. Too bad, however, that the U.S. cover art sucks. Wish it were possible for the reader to choose the British cover. At least when my Kindle is in hand, you can’t see the bad cover of the book I’m reading.
— Annie Pearson

A Series of Unfortunate Coincidences

I’m finishing proofs and approving cover art and copy for two books in the new Rain City Comedy of Manners series (coming soon from Jugum Press).

These books keep running into a series of real-world coincidences. Some examples:

The first backstory I planned for the cyberthriller The Grrrl of Limberlost seemed unique and evocative. I was 20% into the text when my office neighbor in Building 27 sat in my visitor chair distressed, and told a horrifying story of what was happening to his family.

Which was a 1:1 fit against my story premise.
So, I had to abandon that backstory. Distressed, I abandoned that manuscript for a while. It took me till last fall to return to this story, reset the backstory, and finish the book.

Another example: my clever name for a documentary described on the first page of The Grrrl of Limberlost was “My Life as a Chechnyan Dog.” I was nearly ready one Monday morning to hand the Limberlost manuscript to my copy editor Liz, when the news cycle about the Boston Marathon bombing began. Since my daughter works near the blast zone, I was distracted for several days, like the rest of the U.S.

When I came back to prep the copy handoff, I realized “Chechnya” had to go since it resonated inappropriately. An hour spent in an online atlas led to a substitution: “My Life as a Chisinau Dog.”

I’m crossing my fingers that Chisinau doesn’t figure in a controversy or catastrophe by the time The Grrrl from Limberlost is published.

Two days ago I was writing jacket copy for the second book, Nine Volt Heart. The original premise for the story was: could Bruce Springsteen ever have a love affair without asking his beloved to sign an NDA after he appeared on the cover of Time magazine?

So I started my jacket hook from that premise, dropping Bruce’s name. Also, who reads Time magazine anymore? So I substituted Rolling Stone, and pondered how close I could trespass on the song by Dr. Hook and the Medicine Show.

By the time I paused my work to read that day’s fresh online news, the cover of Rolling Stone had wandered into Chechnya territory—creating irrelevant reverberations for Limberlost by reprinting the insipid face of the Marathon bomber.

I can’t substitute Spin or No Depression—not enough readers would recognize those names to create resonance. CREEM and Crawdaddy died, and three-quarters of the people alive today never heard of them. Billboard isn’t relevant for what I want to capture. Only Rolling Stone works—which is why the Jakar picture spawned controversy.

So, Rolling Stone stays in the Nine Volt hook:

Can you find true love without a non-disclosure agreement after your picture is on the cover of Rolling Stone?

See the current Rain City Comedy of Manners series blurbs to read the blurbs. Crossing my fingers again in hopes that I’ve removed unfortunate coincidences from the books’ text and blurbs.

Or maybe in an SEO world, coincidence is good fortune.
— Annie Pearson

Life as an Indie Publisher: Go-Live Task List

I pushed a new Jugum Press title live last week. Today I described the related tasks over lunch with my former Web-master, with whom I collaborated to publish several thousand major content pieces during our work life. She had a look of horror.

Here’s my hideous-tedious task list as Jugum Press managing editor to bring one title live in two formats.
QA for Indie Publishers

Continue reading

Learning Not-So-New Technologies

I’m working on new tasks related to electronic publishing. If you follow any discussions on line, experienced users complain about the tools; new users blame themselves for their own confusion — just like the PC world.

The tools are new incarnations to support project and publication tasks that I’ve been doing for several decades. Here’s what I’ve learned about the new tools and processes I’m mastering:

Lots of important websites suck.
Lots of websites with wizard-like processes also blow.

Continue reading

Partying like it’s PC99

TechBooks
A group from my old Hardware Evangelism team* at Microsoft reconvened recently, just to check in with each other. This is the crew that:

  • Made sure you don’t have to set a jumper on the motherboard if you want to switch between audio and a CD drive.
  • Rid the PC of legacy connectors in favor of USB, got wired and wireless networking to work consistently, drove DVD into the business laptop market.
  • Fixed annoyances like color-coded connectors and making your external mouse and touchpad both work simultaneously on your laptop.
  • Brought 3D graphics to every PC.

And, critically important, we got the industry to design and built hardware so that Plug and Play works.

In the flow of the afternoon conversations, these ideas surfaced about how to drive change: