After many years of blogging, and consistent with my desire to move toward retirement, we have ended the Insights blog. Thanks to Doug Bedell for his years of blog support.

Getting ‘Out There’ Matters Greatly

Posted on March 11, 2016
Filed Under Technology, The Writing Life | Leave a Comment

On his ‘I’d Rather Be Writing’ blog, Tom Johnson in California’s San Francisco Bay area takes the occasion of moving to a new job to reflect on what he was pleased with, and not so pleased with, on his old one. His reflections reveal a conscientious, fully engaged technical writing style, although not a perfect one – on his old job, anyway.

Tom’s first priority, a key resolve, seems to be getting out to where the work is done, to experience what’s happening before he prescribes procedures to keep it happening.

“Understanding the scrum process and how it was implemented,” Tom notes, “allowed me to quickly understand what teams were working on and what documentation needed to be written or updated, and when.”

Like a street-side reporter, you have to be on the street, rather than at your keyboard, to experience what’s actually happening before you start to describe it for others. There’s nothing like “being there” as a first step.

“I like being a part of engineering teams,” Tom notes, “embedded right there alongside product managers, quality assurance engineers, and developers. I built a strong sense of trust and rapport with the teams. I don’t like it when writers are grouped in their own space and interact mostly with each other, separated from the engineers.”

In getting to know the engineers he’s writing for, Tom is almost automatically in closer touch with them – they’re colleagues, not clients in their own “spaces”.

“I learned,” Tom confides, “that you should never send blanket emails to the entire team asking for reviews of massive amounts of documentation, because it will never happen.”

His goals for next time include trusting nothing, testing everything; keeping documentation systems as simple as possible and “diving deep into content, not doc tools.”

This all gets down to becoming, and remaining, authentic in your approach to technical writing. It may seem initially comfortable to be sitting at a wide display with a slick keyboard, but, over time, it’s the content, more than the technique that matters. And you get that from your colleagues. After all, they’re doing the work you’re describing. – Doug Bedell


Leave a Comment

If you would like to make a comment, please fill out the form below.

Name (required)

Email (required)



Email Subscribe