The best advice I’ve ever gotten about technical writing…from programmers


I came to the realization that even working with a group of trainers for the past two years, much of my career as a technical writer has been spent working with programmers and engineers. In my opinion there is a certain kind of magic when working with the right development team. In reflection, I enjoy being around programmers, engineers, and operations people because I like the launch of new products and initiatives so much.

In fact, I am going to say that I prefer working with technical staff and would choose to be a solo technical writer in a technical group versus being a writer in a technical writing group any day.

Here are some lessons about being a technical writer I’ve learned from programmers:

Align yourself to the business. A common complaint I hear about technical writers is how they drift in a world of their own immune to business drivers and technical accuracy where they can wring their hands over grammar, information design, and other topics surely to make a programmer’s eyes roll to the back of their head. It comes down to thinking strategically and asking how can the documentation I create help the business make money, save money, and increase productivity? Granted there are going to be some non-writer managers who are going to want more transparency into the writing side but in the end they want somebody else to worry about those things so the team can focus on the project.

Be as self-sufficient as possible An early technology mentor of mine taught me that there are few if any original ideas in software and if you know one piece of software like a database application, it is that much easier to learn a similar application. It’s never more frustrating to hear a technical writer or even a trainer demand a training class on a new application especially in today’s age of trial versions and demos accessible via the web.

Try to answer your own technical questions yourself first. I once worked with a manager who the programmers found particularly frustrating. To put it politely, she wasn’t too invested in her position and got her job because she was married to one of the company principals. I can remember speaking to one of the programmers after a conversation where he wanted to throttle her and he told me, “Will, always try to answer your technical questions first yourself. It will make it a lot easier for you to get along with programmers in the future.” I took his advice to heart and within reason, I try to answer technical questions first then get help from a programmer or other subject matter expert.

Avoid taking meeting minutes. While some compliance programs want meeting minutes of every meeting and some technical writers consider it a gateway into the inner circle so to speak it is a wrong move for technical writers. More than one programmer I’ve respected over the years has told me to avoid taking meeting minutes because programmers and engineers won’t respect a technical writer who takes minutes and think of them as just a secretary (the traditional role that takes meeting minutes). They also went onto remind me that meeting minutes are rarely ever read beyond the initial meeting. Besides what good are meeting minutes when everybody around the table is taking their own notes anyway?

Have you ever gotten good advice about technical writing from somebody other than a technical writer? What was the advice?

Image by Stock.xchng user: svilen001

Originally published at willkelly.org on November 25, 2011.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.