Technical Writing in Action

by Scott Wilson on January 7, 2017

I was at a party recently and was asked what I do for a living. “I’m a technical writer,” I replied. “I wrote the instruction book you didn’t read when you bought that tech product you don’t use anymore.”

Awkward silence; one woman starting backing away from me.

But one of the strengths of a technical writer, I’ve heard, is perseverance, so I soldiered on.

“For example,” I said to the people still within earshot, “how would you describe this? Try to be pithy but accurate.” I wondered for a second if I should define “pithy” for them.

I didn’t. Instead, I performed a maneuver I had seen in a movie when I was much younger.

“Um, take a giant step to the left”? one person ventured. “Doesn’t quite get the springiness of it,” someone else said. “How about, jump to the left?”

My group was now actually increasing in size and interest, something my previous explanations of technical writing had thoroughly failed to accomplish. Probably the gymnastics aspect, I thought.

“Try to bring some warmth to it,” was my reply, “as if you were talking to a friend.”

“I’ve got it,” said the person who’d mentioned the giant step, “it’s just a jump to the left.”

“Good,” I said, “now step two.” And I did another maneuver.

“That’s easy, step to the right.”

“Can we tie it in with the first step?” I asked.

“OK, how about, and then a step to the right?”

“Perfect,” I replied. “So how about this?” And I performed two actions simultaneously. “Just be short and direct.”

“Alright, put your hands on your hips.. ” and she trailed off.

“Bend your knees?” someone else ventured, clearly new to the group.

“No, that’s a workout move,” was the response. “ How about, bring your knees in tight.”

“Very good,” I said, “but now things get harder. What about this?” And I did the final maneuver of the dance I’d learned from a movie at chaotic midnight showings, never realizing it was my start in technical writing.

Furrowed brows all around. Clearly, I’d gone beyond their developing technical writing skills.

And then an older woman walked up; apparently she’d been watching from across the room.

“My goodness,” she said, “that pelvic thrust is driving me insane.”

And finally someone got it. “So let me get this straight,” he said, “you teach people to dance the Time Warp from the Rocky Horror Picture Show?”

“So it seems.”

Everybody:

It’s just a jump to the left.

And then a step to the right.

Put your hands on your hips.

And bring your knees in tight.

But it’s the pelvic thrust.

That really drives you insane.

Let’s do the Time Warp again.

Words and music (I know you’re singing it to yourself!) by Richard O’Brien.

{ 0 comments }

Part Two: The Talk

I don’t know if you’ve heard of it before, but there’s an organization called Write the Docs that calls itself a “series of conferences and local meetups focused on all things related to software documentation.”

You could be forgiven for not knowing about Write the Docs because, they don’t currently have a Los Angeles area meetup (that I could find), and they are focused on software documentation.

Now you’ve heard of them. More information is available at, stunningly, writethedocs.org.

Anyway, they had a meetup in San Francisco in November 2016 where Andrew Etter, author of Modern Technical Writing, was the speaker.

Here are some of my takeaways from his talk:

  • He didn’t just restate what’s already in the book. I had read the book, so this was a pleasant surprise.
  • He is a low-key, engaging speaker. Again, a pleasant surprise. Not all good technical writers are also good speakers.
  • His new content was good. He spoke about the process of creating an ebook, he provided some additional content related to the recent developments in technical writing, he spoke of his experiences as a technical writer and tech writing manager, and he provided his take on what is the “differentiated value add” of a technical writer. If you don’t know what that phrase means, as I didn’t, he explains it.

My advice: Find the video online (here’s the link: https://www.youtube.com/watch?v=hbl2pgWJquE&feature=youtu.be) and watch it, especially if you read the book and liked it. You’ll learn more about the author, about creating ebooks, and about his thinking of what’s important in technical writing.

For another take on the same talk, visit https://ffeathers.wordpress.com/2016/11/19/modern-technical-writing/.

Part One is an overview of the book Modern Technical Writing, authored by Andrew Etter.

Part Three covers my thoughts on both the author’s take on some of the technical writing best practices and on some of the recent developments in software technical writing that he mentions.

{ 0 comments }

Book Review. Modern Technical Writing: An Introduction to Software Documentation, by Andrew Etter

December 12, 2016

Part One: The Book Modern Technical Writing is available on Amazon. Very reasonably priced. Search “Andrew Etter Amazon” using a web browser and you should have no problem finding it. Modern Technical Writing, for me, is really two books. One part of the book is the author’s take on technical writing best practices. The other […]

Read the full article →

What is the Purpose of the LASTC?

December 5, 2016

The purpose of STC chapters is to provide value to members at the local level. The LASTC does this mainly by: Maintaining a website: lastc.org Job notifications via email: lastc.org/resources/jobs/ Periodic dinner meetings with speaker: lastc.org/events/upcoming-meetings/ Serving as guide to the national STC: stc.org Because the LASTC is geographically dispersed – the majority of our […]

Read the full article →

Fresh from STC Summit

May 21, 2016

Jeff here, with another installment on this year’s STC Summit in Anaheim. Arriving at Summit! Admittedly, I did not set up my attendance for maximum success: due to work demands, I was only able to attend one day–Monday–which greatly curtailed my overall experience (Summit is a three-day event, with two pre-conference days). And due to a […]

Read the full article →

Wednesday’s Out of the Box Workshop

May 20, 2016

At breakfast, I re-read the workshop descriptions. The panel, Tech Comm Throwdown: 2 Experts Enter, 1 Winner Leaves, sounded interesting. What was this? It didn’t read like a typical panel description. “Mixing fact and fun, experts debate topics which may include…”—fact and fun? Intriguing. I’m curious what this panel is about; maybe I’ll go. Then […]

Read the full article →

STC Summit—Tuesday’s Workshop Tips

May 20, 2016

From the many choices, I selected these workshops: DevOps Docs: Fast, Great Content for the Cloud Vanessa Wilburn (IBM Corporation) Constantly changing GUI/features; documentation changes need to be as real-time as possible. User stories that address the customer’s needs. Need the right tools to move quickly: Agile; automate as much as possible. Writers attend stand-up […]

Read the full article →

STC Summit—Highlights from Sunday and Monday

May 17, 2016

I climbed the Summit and am enjoying the view! The speakers at #STC16 have shared insightful and detailed information. Here are some tips I’ve picked up so far: Sunday Night Opening Keynote David Rose, shared his view of Internet of Things. David focused on the scenario of Enchanted Objects: ordinary things that function the way […]

Read the full article →

Fine-Tune the Colorful Summit Guide

May 5, 2016

This week I revisited the Summit Guide and focused on Strategy 3. Looking at my highlighted hard copy, I realized I do need a clone—preferably several clones—because there are at least three sessions in each block I want to attend! I re-read the workshop descriptions and paid attention to the tracks. Great news! Some of […]

Read the full article →

Summit 2016 is coming: are you ready?

May 1, 2016

Hard to believe that Summit 2016 is finally around the corner, just two short weeks away. After hearing the location–Anaheim!–was picked shortly after last year’s Summit, I quickly added the dates to Google calendar. I was so grateful to hear that finally Summit was arriving to my back yard in Southern California. Sure, I had […]

Read the full article →