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.

Remote technical writer best practices


I worked on my first remote technical writing project when dial up was still dominant in homes, and I find myself still learning as I go along. Remote technical writing projects can work. However, I’ve come to see over time that not every organization can support remote writers. Likewise, not every writer is cut out for working remotely.

Here are a few best practices I’ve come across over the years:

Use the cloud for file hand off and version control

I’ve been burned myself so many times by emailing files back and forth that I should know better. While it’s not a factor when writing articles or blog posts (lightly formatted and simple documents), it is a factor when working on more complex documents. Now with cloud platforms like Podio, Dropbox, and Box that include free cloud space price isn’t an option to not setup an option for file hand off and version control.

Another benefit of using the cloud is it offers better support for alternative work schedules and projects that span time zones. It’s better to have files in the cloud versus the email inbox or local hard drive of a part-time off hours technical writer for security and convenience of other team members.

Use social task management tools to keep the project on track

Asana and Producteev offer intriguing (and free!) options for tracking all the tasks around documents. In fact, I use Asana regularly for editorial checklists on a corporate project and when writing articles and blog posts

Remember not every organization is remote writer compatible. For a range of reasons that aren’t entirely the remote writer’s fault, there are some organizations that just can’t support a remote writer for reasons of corporate dysfunction, politics, and other such things.

I’d like to say that I have sure fire way of qualifying such organizations but I don’t have that trick down yet. Way back when I was a computer book technical editor, the publishing industry had worked with remote contractors down. Remote writer compatibility, usually, breaks down to the following:

  • The right kind of writing project
  • Communications
  • Project management

Technical writers get ignored enough in some organizations when they are in a cubicle at the end of the row. When a technical writer is faceless, it adds another level of potential error into the usual project communications mix.

Use track changes and comments

While it’s easy to hate on Microsoft Word, Word’s track changes and comments are ideal for edits and reviews on documents because they leave an audit trail that’s easy for other team members to follow. Any comments that aren’t approved can always be rolled back. Alternatively, you can review documents as Adobe Acrobat PDFs with the Adobe Reader’s annotation tools.

Write emails, questions, and review comments that can stand on their own It’s one thing to have to defend and add clarity to your communications and comments while working in the same office. However, it takes on an added shade of importance when working as a remote writer.

Use mobility as a redundancy

I keep many of my working files in Dropbox so I can access them while I’m away from my PC from either my iPhone or iPad. I’ve also had to send out client emails during one of the usual Fairfax County, Virginia storms to alert clients when my power was lost.

What are your remote technical writer best practices?


Originally published at willkelly.org on August 30, 2013.