This
post provides a look at the "technical writing principles" I've found
useful in helping writers to become highly effective and valued as a member of
an engineering team.
- Be a lifelong learner
To be an effective writer, you have to be a lifelong learner, get motivated enough to learn new technolgoies. For tech writers, learning continues from the cradle to the grave.
- Have
a positive attitude
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 on your attitude. Sometimes, you may be given an assignment that has nothing to do with creating 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, and technically reviewed. Make sure that when you start something, you 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 - Make it clear to all stakeholders' what outputs to expect at any given point of time in the product life-cycle.
- Review - Use the Google doc or Adobe Shared Review process to receive feedback.
- Communication via emails/slack/meetings - Keep the stakeholders informed about the progress of your documentation. Use the email meeting to schedule appointments 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 create User Manuals, API documentation, Training Materials, Engineering Blogs, etc. Technical documentation is meant for users of the engineering product. The users may be within the company or external; they may be engineers or layman. Understanding the users 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 such as:
- Wrong content
- Incomplete work
- Poor impression on the documentation team
Writers must avoid ambiguity in the documentation so as not to muddle others.
- Inhale
and Exhale Content
Writers 'live and breathe' content. They consume content, and they create content. Practice your craft to serve the readers. Don't expel raw material but transmute it to provide what the reader most wants.
- Trust
facts - Question assumptions
Related to the principle of avoiding ambiguity, writers must never make assumptions.
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 engineers 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 and writers. 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
- Gather analytics
- Use Style Guide
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. Create a documentation plan to set expectations for all the stakeholders.
- Identify
priorities
At the end of the day, the most important Technical Writing principle is "If you do not know - ASK". Writers must ask questions until they are confident that they have the information needed to write content. Just remember, unanswered questions contribute ambiguity to the content.
- Escape the curse of knowledge
Close the writing loop by getting feedback from users. Show the draft to people who are actual users or atleast to the developers / QA, and find out whether they can follow it. Only when we get the feedback, do we discover that what's obvious to us isn't obvious to them. A writer should revise in response to comment when it comes from users.
- Have a thick skin while receiving feedback
You want to encourage folks to share their honest reactions to what you write. And if your documentation is useful and focused, timely and fresh, and you've written it with passion and voice about a subject you know a lot about, then your readers are likely to leave terrific feedback. But occasionally you're going to hear from people, especially from Editors, who disagree with you or who don't like your style or approach and give you rude comments. And that's never fun. It's taken me years to learn not to take that stuff personally, but take it with a grain of salt.
