Search icon Looking for something?

Letter to a Young Writer
2014, Q3 (July 14, 2014)
By Sheila Loring, Immediate Past President

With the influx of summer interns, I've been considering the best way to train a budding technical writer. What essential principles must a new writer grasp to be successful? And how can I provide a valuable learning experience while getting my own work done?

The Carolina Communique first came to mind. Some of the best writers and editors in our field have been providing sage advice for over a decade. Search the archives and you'll see.

This article summarizes the invaluable lessons you can learn from reading the Communique and ends with my personal mantra.

Edit and then edit again.

Users are busy and often frustrated when searching your carefully crafted help system. Your goal is to help them quickly achieve a task or understand a concept. Pare down your words to the most essential. For details, read Michael Harvey's article Less is More: Applying Minimalism to Our Writing.

Consistency is King.

Use consistent terminology throughout documentation. Refer to user interface (UI) items the same way in all instances. "Select" a menu item, don't click it. "Click" a button, don't select it. If you describe the Undo button as "reversing the last action" in one location, use the same wording elsewhere. Your writing is then predictable, scannable, and also easier to translate. Identical sentences are translated once and reused in all instances.

"What a dull book!", one might think. Users don't read technical documentation for pleasure. They want to understand quickly and get back to work. Read more in Sue Kocher's article Is Consistency Boring?.

Help users find help.

The days of reading a chapter from start to finish are long gone. Users search, whether they're reading help systems, PDF files, web pages, or e-books. Write descriptive headings to help them scan a topic and quickly locate information. Place the most important keywords at the top of a topic, where the reader is more likely to linger. Keyword placement affects search results, so this is especially important if you're writing content that's available on a web site.

Play well with others.

It takes a small village to write good doc. You must be able to communicate well and cooperate with subject matter experts, fellow writers, editors, technical support, customers, and your manager. Besides, who wants to work with a curmudgeon?

Consider role playing with an experienced tech writer. For example, practice interviewing a developer. STC offers free archived webinars on professional development to members.

Always be curious.

The desire to understand "how" and "why" motivate you to keep learning. The best tech writers I know love digging into a new software feature and figuring out the best way to clearly explain it to users. Being continually curious can also increase job satisfaction. Read my article Always Be Curious for more information.

Contact Sheila Loring at editor at stc-carolina dot org. Read more articles by Sheila. End of article.

More articles like this...
Comments powered by Disqus.