Tag: Content Strategy

Avoiding Mission Impossible technical writing projects

Photo by Aaron Mello on Unsplash

I’ve had the great fortune in my career to work on some very tough projects — in what I like to call documentation unfriendly environments — and won some and lost others but learned so much about technology and how to work independently as a technical writer.

Before I accepted my current position, I had the opportunity to speak to an organization which has what I quickly came to ascertain what could be a “Mission Impossible” documentation project where there would be more chances for things to go wrong than there was to go right.

After speaking to the recruiter who set up the meeting for me, I began to think how had I won the mission impossible projects versus being “the previous technical writer.” Keys to success include:

Strong technical team

A strong technical team — not to write the documents mind you — but like it or not the IT industry is peppered by a lot of smart people and a lot more people who think they are smarter than they are. If you have genuinely knowledgeable and capable people in the critical technical roles, then half your battle for extracting technical information is won in my experience. If the wrong people are in critical roles, the holes and gaps that sometimes happen in technical documentation can expose the shortcomings.

Proper technical writer/developer relationships

Relationship with the technical team where you as the technical writer isn’t an unnecessary drag on personnel or other resources. Technical writers who need their hand held or can’t work independently are only going to be set up to fail when it comes to a mission impossible project.

Product management and developer collaboration

Strong product management and technical team cooperation and communications. If Product Requirements Documents (PRDs) or stories are just being thrown over the transit without much dialog between product management and the senior members of the technical team, then the hijinks can ensue.

Access to test environments

Access to test systems and the bug tracking system because reverse engineering of technical documentation does often occur especially if the document efforts begin well into the development lifecycle.
Reality vs. vaporware can also come into play on such document projects. If for some reason, you are continually denied access to the system, don’t take it personally, but be on guard that the product may in whole or part not exist except for visions in an executive’s mind.

What are your keys to success on “mission impossible” documentation projects?

My name is Will Kelly. I’m a technical writer and content strategist living and working in the Washington, DC area. My current focus is thought leadership and technical marketing content. I got my start writing user guides, administrator documentation, online help, and later moved into SDLC documentation. My articles about enterprise mobility, BYOD, and other technology topics have been published by IBM Mobile Business Insights, Samsung Business Insights, TechBeacon, CNET TechRepublic, and others. Follow me on Twitter: @willkelly.

3 things technical writers can learn from screenwriters

Photo by rawpixel.com on Unsplash

A few years back I took a screenwriting course through Georgetown University School of Continuing Studies.

It was a challenging course. The professor had a bit of an ego so I didn’t get as much out of it as I had hoped. Recently, I came back to some of the lessons I learned in the course:

  1. Write the picture. Screenwriting is all about telling the story in pictures. After taking this call and reading some screenwriting books, I am definitely rethinking how I approach article writing and technical marketing communications. Heck, for that matter, I may rethink even how I write procedures and product descriptions depending on the document. It’s been a wonderful creative exercise thus far and is pushing to make time for more creative writing into my schedule.
  2. Elicit emotions. Once upon a time, I was a college English Major who won campus wide awards for short stories and poetry. It feels like a lifetime ago after years writing about topics like network architecture, telephone number provisioning, and online collaboration. Technical marketing communications does need to elicit some emotion in order to elicit action from the reader.
  3. Get into the details of the story. It’s no secret that I rail against the so called technical writers who think they don’t need to be conversant in the subject they are writing about. Screenwriters spend time researching at the script treatment and scriptwriting stages so they can tell their story.

I’d like to return to screenwriting at some point and still find myself looking for another course to try.

Hi! My name is Will Kelly. I’m a technical writer and analyst based in the Washington, DC area. I’ve worked with clients like NetApp, Dell, and Neustar to develop technical, training, and thought leadership content. My articles have been published by IBM Mobile Business Insights, TechBeacon, CNET TechRepublic, Network World, Toolbox.com, ZDNet.com, and others. Follow me on Twitter:@willkelly.

Do organizations need technical documentation style guides?

Photo by Oliver Thomas Klein on Unsplash

Do organizations need technical documentation style guides? It’s a question that rises on online forums every so often. Today’s ever-tightening workplace budgets should also put the role of the technical documentation style guide under the spotlight.

My answer to the style guide question is “Yes, organizations do need a style guide, but it shouldn’t dominate the documentation development life cycle.”

With the prevalence of online documentation and the web to deliver information plus more iterative development and launch cycles, the style guide should foster productivity and consistency not stand as a roadblock in the way of technical writers and training developers making deadlines.

My Concept of a Style Guide

Over the years, I’ve become a fan of more lean style guides. Cover the basics of product naming, corporate branding, and anything industry/audience specific and leave the style guide at that. The document should be in a quick reference format, and all document authors should be briefed on the style guide before being let loose on a technical writing project. Sure there are many things that such an approach to style guides may leave out, but that is where standardizing on an industry style guide like the Microsoft Manual of Style for Technical Publications or ReadMe First!.

Decision Making about Styles

Indecisive decision making over stylistic issues is boorish and counterproductive, and in the end, there is no benefit to the document, project or end client. Running with a lean style guide means the occasion may arise where a stylistic decision is made on the fly.

This only works when a senior writer or editor is given ownership over stylistic decisions. Any stylistic decisions must be documented in a style guide update. Having one “keeper of the style guide” avoids dragging out stylistic decisions by committee.

Know Thy Audience

Just like writers need to understand their audience for the documents they are writing, this understanding needs to carry over to the style guide. If the style guide serves up too many items that are lost on the reader of the end documents, then the style guide is ineffective.

Likewise, if the writers tasked to follow the style guide have issues understanding it then the style guide also fails. If the style guide is full of contradictions, it fails again. The style guide is a supporting document, and when that is forgotten, the style guide fails.

The style guide should be a guide not an obstacle to publishing documents.

Hi! My name is Will Kelly. I’m a technical writer and analyst based in the Washington, DC area. I’ve worked with clients like NetApp, Dell, and Neustar to develop technical, training, and thought leadership content. My articles have been published by IBM Mobile Business Insights, TechBeacon, CNET TechRepublic, Network World, Toolbox.com, ZDNet.com, and others. Follow me on Twitter:@willkelly.

Is “3” the answer to many of your document problems?

Photo by Tobias van Schneider on Unsplash

I’ve spent the better part of my professional career as a contract technical writer. During that time I got the chance to examine why some organizations struggle with their technical documentation. With limited resources and budget, it is sometimes too easy to shortchange technical documentation and other written communications. With some realistic planning, this doesn’t have to be the case.

Recently, I was talking with a marketing consultant friend of mine, and we were discussing documentation problems and how small companies could get past them. The number “3” kept resonating for some reason.

  • Three drafts because in the end any more drafts like that aren’t going to improve the document much and anything beyond that can dunk a project schedule underwater unnecessarily.
  • Three document review cycles before declaring the document final because beyond that mean splitting hairs over minor issues that may not be picked up in the final product anyway.
  • Three sets of eyes on the document because even two sets of eyes can miss something.

Granted our discussion centered on developing technical documents on small project teams but do you think “3” is the answer to many technical documentation problems?

Hi! My name is Will Kelly. I’m a technical writer and analyst based in the Washington, DC area. I’ve worked with clients like NetApp, Dell, and Neustar to develop technical, training, and thought leadership content. My articles have been published by IBM Mobile Business Insights, TechBeacon, CNET TechRepublic, Network World, Toolbox.com, ZDNet.com, and others. Follow me on Twitter:@willkelly.