Principles of Technical Writing



A good writer must arouse curiosity amongst the readers. They must use their craft to service the readers, not to expel raw material but transmute it to provide what the reader most wants. This post provides a look at the "writing principles" I've found useful in helping writers to become highly effective and valued as part of a product team.



You have to know how to collaborate and be a good judge of people. Additionally, you must be willing to interact with different personalities of the people you are working with. There is an innate skill to draw information out of people or get your work reviewed by the SMEs without aggravating them.The success you experience as a writer depends 100% on your attitude. Sometimes, you may also be given a frivolous deadline or a writing assignment that has nothing to do with user documentation. But you must display a positive attitude towards such requests. 

Quality should be the priority
Your job is to make sure that your work is complete, correct, thoroughly fact-checked, thoroughly reviewed, and to make sure that when you start something, you actually
complete it. If people know they can rely on you to do high-quality work, you will win the trust.

Communicate, Communicate, and Communicate
Writers should strive to be superior communicators, as ineffective communication leads to confusion and reflects poorly on the entire team. The writer will be judged by the quality of his work. For better quality, communication is the key factor:
  • Documentation Plans - Making it clear to all stakeholders' what document outputs to expect at any given point of time in the product life-cycle.
  • Review - Using the Acrobat's Shared Review process to receive inputs from multiple readers on the same file.
  • Communication via emails/chats/meetings - Keep the stakeholders informed about the progress of your documentation. Use the email meeting to schedule appointment with SMEs, and Product Managers. Ad-hoc chat also works depending on your relationship.

Know Your Assignment

Like it, or not, writers are 'contractors’ who are hired to provide User Manuals, API documentation, Training Materials. Technical documentation is meant for the external customers. Understanding the external customer will help to improve the quality of the writing and, ultimately, the quality of the product.

Avoid Ambiguity
This implies "Never presume" and clarify whenever there is ambiguity. Making speculation about how a product’s features/functionality, schedules, etc. will lead to a variety of issues:
  • Wrong content
  • Incomplete work
  • Bad impression on the documentation team
Writers must avoid ambiguity in the documentation so as not to muddle others.

Content! Content! Content!
Writers 'live and breath' content. They consume content, and they create content. Content is provided by other teams that help in making intelligent decisions:
  • Requirements 
  • Specifications
  • Design
  • Etc
Content produced by the Writers is used to assist the user information experience:
  • User Manuals 
  • Technical White Papers
  • Standard Operating Procedures
  • Installation Guide

Trust Facts - Question Assumptions 

Related to principle having to do with avoiding ambiguity, writers must never make assumptions. As doing so can have a significant impact on the entire business.
Writers must:
  • Work with the cross-functional team to address issues with requirements, user stories, etc
  • Clarify schedules/expectations when in doubt
  • Leverage documentation plan to articulate and set expectations on the documentation
  • Track/manage outstanding issues until they are resolved 
  • Ensure a thorough document review by developers and stakeholders

Think Innovation

Regardless of your busy schedule, writers must think out-of-box. Improvement ideas should be socialized, shared and investigated with managers. Small changes can make a huge difference to the organization. Innovation that can benefit the documentation is always welcome.
  • Tweaks to processes, templates, style guide
  • Suggest better tools 
  • Use Videos where possible
Remember, the companies are always looking for ways to increase efficiency and make the most out of the limited documentation budget.

Embrace Restrictions
On the surface it may appear as if style guide does, in fact, restrict the writer; however, if you dig deeper you will discover that style guide helps by improving communications by establishing consistency in all the documents.

Plan Wisely
A well thought out and a documented plan is worth its weight in gold. The documentation plan is the primary tool used to set expectations for all the stakeholders.
"If you fail to plan you plan to fail."
There is a limited budget for documentation, and it is your responsibility to ensure the effectiveness of the plan such that it provides the highest ROI (Return on Investment).

Identify Priorities
At the end of the day, the most important Technical Writing principle is "If you do not know - ASK".  Writers are expected to ask questions until they are confident that they have the information needed to write content. Just remember, unanswered questions contribute ambiguity to the content and add risk to the business.

If you have any questions, or you want to hire me, send me an email at abeeshthomas@yahoo.com. If you want to outsource your writing and documentation projects, visit ThomasEcafe.com, or email info@thomasecafe.com or call +65-82086393. 

No comments:

Post a Comment