It was a refresher to spend a friday evening listening to Leah Guren sharing her insights acquired from a 30 year old career in Technical communication. She talked about the fundamentals that lay at the core of Technical Writing. The focus was on what process is followed, what are the right questions to be raised, how well the information is analyzed rather than any particular tools or domain. The talk was titled “The Golden Rules (Technical communication theory and application)”.
She discussed 10 Golden rules that work for all types of TC projects and provide a practical methodology. These golden rules are a result of Leah’s own experience and research.
#1. Paper is Permanent
It’s about owning what I am writing. It says “I am responsible for what I am writing”. So its important to write correctly, proof read and edit the documents properly and provide a proper structure to the content.
Lets see why is it so important…..
Get your grammar and punctuation rules correct so as to give logical explanations to developers.
#2. Know you Audience
Who is the user, its essential to know who is going to use the document, include demographics, take into consideration the technical and product knowledge of the users, analyse the language skills of the users. Make safe assumptions.
Ask yourself
Who Am I?
Have you heard about FOGG Index? It tells you how good or bad is your writing and does it match the learning level of your audience. Check out FOGG Index
#3. Highlight Hazards
Watchout for things that need special attention of the user, Figure out the pain points, high risk things and use proper means to clearly specify the hazard.
As a Technical Writer your job includes:
#4. Break it Out
Do you know 7 years ago it was known that users spend 30 secs on a page to look for information. What’s crucial for a Technical Writer is giving proper structure to the content so that its easier for the user to find the information.
What can you do?
#5. Don’t write blind
If you don’t understand do not write, it’s your job to know what you are writing. Important to know the product you are writing about. Do not rely on second hand information. Explore the product, see it, use it, touch it because if you cannot perform the action you are writing you cannot explain it correctly.
Ask open ended questions to get the right information from the SME.
#6. Be Consistent
When you are writing the same thing in three different places in the document do not write it differently each time. This is exactly the opposite of what we are taught in school. But that’s the rule here. Take care of technical terminology and pick one term. It’s even important for localization.
So,
#7. Signpost!
Use signposts to direct the user to the correct information at the appropriate place in the document. Provide proper references wherever needed. Use layout and typography to indicate relationship of elements. As part of a documentation suite make all parts aware of each other.
#8. Don’t violate (legitimate) standards
#9. Contemplate before you illustrate
Make a rational decision when you must have graphics. Sometimes you may not need it at all or maybe you may need only a part of it.
What to do,
#10. Cut the fluff
Flowery, vague language is fluff also. Fluff is a serious issue with usability. So Keep it simple and short (KISS)
Common flufffs:
So, these golden rules are intended to provide a user centric approach to documentation, help to justify editorial choices, and provide the analytic decision tree for all projects.
The topic was not only interesting but her approach to presenting the topic and her style of engaging with the audience made the experience even more enriching.
Note: Main points are taken from Lean Guren presentation handout notes shared with the audience.