Learning Sessions

This category contains 2 posts

Back to Basics – The 10 Golden Rules of Technical Writing

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…..

  • Users judge the quality of product, s/w based on the quality of documentation.
  • Quality states the measure of accuracy (absence of errors), like typos, spellings, punctuations, incorrect data.
  • Usability defines clear and accurate information.
  • Is the content standalone?
  • Can someone use it?
  • Do you understand what you are writing?
  • Is the information misleading or ambiguous?

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

  • Are you communicating to existing users, experienced users, novice users.
  • How users are consuming the content, online, printed, and so on.
  • Does the documentation takes care of special needs of a percentage of audience, such as color blindness?
  • Are you adapting yourself to the type of audience.

Who Am I?

Who we are?

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

  • Do you engage with tech support to find out the pain points, how good is the content, what is working for the user what is not working.
  • Are you taping other internal resources like marketing team to get feedback on the user docs.
  • Engage with the customer.
  • Create Personas. An artificial or fictitious person/s who represents the user/s, put it in front of you and check at every point, are you writing for the right person.

#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:

  • Finding hidden hazards through scenarios.
  • Use a ranking mechanism to differentiate types of severities
  1. Danger
  2. Warning or Caution or Attention
  3. Note
  • Make hazard visually clear by placing it at the right place.
  • Break it out of body text
  • Highlight it, Use icons, Write imperative sentence, Use a simple do/do not statement
  • Explain the ramifications and workarounds

#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?

  • Keep the sentences short.
  • Think visually and reduce the text, use graphical illustrations if useful
  • Provide structure to documents, use headings, bullets, Include tables, Steps, Flowcharts for decision making and branching options in a process.
  • Think about the way people need information(text, non-text).

#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.


  • Decide how to refer to the product.
  • Consider interface elements and actions
  • Don’t forgot styles, fonts, and layouts
  • Use a style sheet.

#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

  • Do not use non-standard terminology.
  • Recognize the difference between a legitimate(de jure) rule and a bad de facto custom. So if you find certain things to be mere customary as they have been passed from generations of writers, whereas its incorrect and is not a proper usage. Go ahead, make yourself heard and change it.
  • Develop knowledge about issues relating to, regulatory and compliance such as ISO compliance, EU directives or any certifications or legal issues.

#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,

  • Use appropriate graphic types
  • Use callouts or annotations to focus attention.
  • Use various image views like exploded view, isometric view, and so on.
  • Place the graphic after the content.

#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:

  • formal and pompous writing
  • hidden strong verbs
  • unnecessary passive voice

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.



A day on CMS and Author-IT

On Saturday 19-may-2012 I attended a one day workshop on CMS and cloud based authoring with Author-IT as part of the Technowrites Connect Learning Sessions. The session introduced us to the concept of Content Management System, Cloud based authoring, and collaborative reviewing using Author-IT.

Rajdeep Gupta, the Business head of Author IT Asia conducted the seminar. It was an informative and interesting session as this was my first interaction with a CMS Tool for Technical Documentation. As I have used a Software Configuration Management Tool called Rational Clearcase from IBM for 4 years I could draw many parallels, but Clearcase is extremely huge in that sense.

The session focused on the benefits of a CMS and its need for organizations to efficiently manage content, increase content reuse, single sourcing and achieve faster time to market. The Author-IT CMS offers the features of:

  • Embedded Text for multiple replacements
  • Structured Authoring to prevent mistakes and maintain consistency
  • Reduced Time to market with a real-time reviewer using Author-IT Reviewer
  • Lesser Translation and Localization costs as Author-IT sends content that needs to be re-translated. Content is send in XML format.

The Author-IT on premises version of the Tool packs configuration capabilities for administrator that offers a flexible approach to manage the documentation projects with comprehensive control mechanism for the projects and access privileges for project members or groups. The UI of the Tool has been smartly designed to resemble Microsoft Office Suite, this is indeed smart enough to make the users feel confident on their first interaction with the Tool.
Author-IT follows Object Oriented Design methodology wherein all the elements or components of a document are treated as individual objects in relation to each other. All these Objects are contained in a higher level Library. A library will also consist of all your project working folders, templates, styles and so on. For one organization it’s recommended to have one Library although importing content among different libraries is permissible.

The Author-IT cloud based model is customized to organizations with limited budget or short duration requirements for a help authoring solution. The distinguishable feature of the cloud based model is its faster ramp-up and implementation time along with the other benefits of cloud based solutions from anywhere anytime access to lower operational costs. A one-hour hands on with the application helped us to get ourselves familiar with the Author-IT cloud.

The Author-IT solution sounds convincing for organizations with huge documentation needs and greater need for single sourcing along with shortened and faster review mechanism. So if your documentation workload is huge and involves large and multi location teams you may consider exploring the Author –IT platform.

An interesting take away from the session was on the nuances of evaluating a Tool for your organizations. Rajdeep shared some useful insights drawn from his experience as a Usability Expert like focusing on the Usability aspect of the Tool, amount of integration effort required to deploy the Tool, Cost, and so on. The concept of taking out surveys within the organization and different users, collecting, consolidating and analyzing their feedback is also crucial for the success of a new Tool to be introduced in the organization.

All in all it was a very valuable session esp for me when I am trying to understand this field and its vastness, challenges, solutions each day. It introduced me to yet another frontier of Technical Communication.


I am on Twitter