Search results

Guest Post: Core Skills for Technical Writers Often Overlooked

by Tom Johnson on Aug 16, 2012
categories: technical-writing writing

Vinish Garg

The following is a guest post by Vinish Garg, Director of Operations in Technical Documentation at vhite systems.

When I watched the Master Chef series (Australian version and then Indian version) last year, an important lesson for contestants was to not focus only on extraordinary or most creative dishes. The judges never really looked only for creativity, fancy ingredients, and garnishing. To the judges, adherence to instructions, balance, presentation, and the basics of a dish was equally important.

Most of the tech comm resources, including blogs, white papers, open forums, presentations, and workshops at local or global events, talk about topics such as XML or DITA, single sourcing, indexing, documentation management, or usability. It makes sense since we all know that the technical documentation practices are evolving faster than ever before. So the current and next generation should be well-equipped to handle the challenges.

However, I feel that somewhere along the way, mastery of the basics has been overlooked.

I have been developing technical documentation for eight years now. My general work routine involves (a) being a documentation manager, (b) training new technical writers, (c) writing procedures and instructions, and (d) participating in online community activities.

At this stage, I feel that the industry veterans are passing the baton to me, and at the same time, I am passing the baton to the next generation of technical writers. I have also realised that passing the baton to next generation is a greater and more challenging responsibility since they look to us for input and direction.

The Current Generation of Technical Writers

When I look to hire contractors, the most important factor for me is to evaluate the documentation and professional skills in the resume itself. While responding to open positions for my projects, many candidates apply with two to six years of experience. They claim to have developed world class documents in agile work environments, using global technology and enterprise platforms.

However, I am often let down. Here's how:

  • Email: The emails that applicants write when applying for an open position are poor.
  • Resume: The resumes are even less satisfying.
  • Professional etiquettes: There is no follow-up, and no thank-you emails.
  • Last and most unfortunate: When they ask me for comments or feedback, a few of them scoff at my polite yet professional comments.

The ability to fix CSS, compile the help file in Flare, set up a wiki, or use cross references in Microsoft Word are all good technical writing skills. But I wonder if this is enough. How can an experienced technical writer apply with a poor resume (most of the resumes are pathetic)?

Basic skills, especially writing skills, seem to be missing somewhere. And when I see that eight out of every ten candidates lack these basic skills, it's unfortunate. I would go so far as to say that this is a disrespect to the profession.

In a way, it is like the chef who places the knife on the left side of the plate while serving a dish. There is more to being a good chef than merely knowing about garlic, olives, cream, and spinach. It's also about mastering the basics.

The Responsibility

I guess there is nothing wrong with the way these technical writers were trained or groomed. Grasping the basics comes from within. Qualities such as attention to detail in email, a well-written resume, and the whole approach to apply and then respond professionally to open positions are not required to earn additional points in the interview. These qualities should be mastered by one's own sense of pride as a technical writer.

A good resume and a professional email can demonstrate a technical writer's core competencies. These two simple outputs help show the communication skills of a technical writer, provide respect to the profession, demonstrate value in being part of the technical communication community, and help pass standards on to the next generation.

The Spirit of Documentation

For technical writers who miss the basics, there are often no questions about their documentation skills. The manuals they develop may be excellent. I would not be surprised to see that their documents meet the agreed usability criteria, follow style guidelines, adhere to processes, and are delivered on time.

Despite this, I suspect that the "soul" of the documentation is missing somewhere. I can't quite pinpoint it -- I am still looking for answers. But it seems their priorities are a little off. Why is it that planning an index is more important than clearly articulating the technical concepts of the application? Why is that writing a professionally accurate email is less important than drawing up project requirements? Why is it that attention to grammatical detail becomes secondary to promoting the latest agile scrum methodology? It's the "little" things that get left behind.

The Challenge

We can expect a similar apathy from the beginners and the next generation of technical writers, largely due to the current socio-psychology of society, coupled with easy and increased access to technology. Their zeal to learn and master tools, training programs, and advanced documentation practice is an encouraging sign. In the same tide, we need to ensure that they too do not skip over the basics.

The fresh graduates do not hesitate to send me a LinkedIn request, or to connect with me on Facebook, or even for Zorpia and other social media platforms. I do not mind this, but when I see that it's more important for them to build their online profile than to maintain professionalism in email or other communication, I think this is unfortunate.

We cannot afford to overlook the basics. We need to ensure that young hands align well with veteran hands. Let us cultivate a work culture that instills a sense of professional responsibility along with the pride of being a technical writer. We need to ensure that we do not forget basic writing skills.

Vinish Garg works as Director of Operations in Technical Documentation at vhite systems. For the last eight years, he has developed technical documentation (B2B, B2C, and B2E) for global businesses.

You can learn more about Vinish at the following links:

To contact Vinish, send him an email at [email protected].

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.