archives

Technical writing

This tag is associated with 4 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.

So,

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

 

Advertisements

Job Hunt

I am new to the world of technical writing and had to accomplish the challenging task of getting a job as a Technical writer with a good organization with all my experience in the IT industry. I went in a strategic way and thankfully things fell in place. So, here I am sharing my experiences with the community.

The three-pronged approach:

  • Creating a worthy resume along with a short description consisting of overall professional description that speaks for itself.
  • Making the best use of online platforms, social as well as professional networking sites, to forums that have relevant information.
  • Most important, patience, patience, and bit more of perseverance.

We all know the first interface of a job seeker is the résumé and hence its an essential tool that needs attention to detail. I happened to create a decent resume by getting feedback from my friends while I was working on the résumé template and the content. Their comments and suggestions were very helpful in setting aside a good resume. Fortunately this exercise has actually taught me how to create better resumes and I am glad I am able to help two of my close friends to set up their resumes now.
Most of the communication is through emails and hence a message body describing about my professional experience in a nutshell along with the a reason of why I am interested in their profile increased chances of hearing from interested recruiters. So a nicely written cover letter definitely helps.

A job seeker’s destination is mainly job portals, but lets admit they are not your best bet for a Technical writing job. This domain in India largely thrives on referrals as I have noticed and makes professional networking indispensable, but a newcomer needs a different approach in absence of a professional network of friends and colleagues. For me, my presence on the web helped. I am a fairly active user of the professional networks and hence the power of linkedin helped me. A lot of good jobs are posted on linkedin, so don’t undermine its potential, to share you a secret I am where I am because of it :).

Few good places to look for latest jobs directly from companies are:

  • The twin-india forum, job section.
  • Technical writers of India, Facebook group.
  • Of course search for jobs on LinkedIn.
  • Monster response is better than Naukri, with no offense intended but job portals are largely flooded with contracting job assignments.

In my case, to my pleasant surprise the blogs earned me a great deal of help. I never knew when I started personal blogging it could turn to be of interest to professionals. That’s the key these days, the interview patterns are changing as I noticed, it’s not only your  knowledge and attitude that will get you through, people have started to show interest in the overall personality of the person they are hiring and somewhere lost values are finding their ground again. I liked Red Hat approach of hiring and I am indeed glad that I am able to be a part of it.

Not to forget, good preparation, a level headed approach and a bit of trust are enough to help you sail through.

Impressions of a Lone Writer

It’s quite likely for a Technical writer to work as the sole contributor towards the documentation needs of an organization. I had this recent experience on a work assignment with a Software company in Pune. While my journey of 3-months was smooth as my reporting manager, SMEs, CTO and CEO were very cooperative and understanding and it proved to be a wonderful learning experience. But as a writer it does becomes bumpy as you are the only person with the reins in your hand.

In this scenario, the writer is his own Boss with ample freedom to carry out the tasks. This gets tricky, as you find yourself at sea initially and at the same time the sense of responsibility is huge as you are the single owner of the work. So, in a way you are your guide and mentor simultaneously. A few impressions out of the experience are shared here:

Not a straw of support
Human habits are tough to break and when you are used to discussing work scenarios with your peers you have to fight your way out to break that habit. Be ready to face problems such as choosing the right Tool, or resolving a tool error, finding the best solution to a recent problem, and so on for a task. Nevertheless, one tends to learn more, by self-exploring and trying. Trust that internet is your best friend.

All in One Role
I am a Technical writer but not anymore, now I am the reviewer, editor, self critic all in one. It is impossible to do justice to these roles by the same person. So a simple trick is to pipeline the documents such that the writing, language reviewing and editing of the same document do not follow the same sequence. My sincere apologizes that I just screwed the DDLC.

Discover the Manager in you.
Gone are the days when I had the luxury of a Documentation manager. Now  I need to self plan the project, decide the timelines figure out the deliverables, set up the Technical review process with the Teams. Be ready with answers for the reporting head, sometimes to defend and justify your position. A key is to be proactive in reporting the status, pointing out glitches, informing in advance that you may need more time rather than waiting for the final day. Importantly keep the reporting head in loop for the delays that are happening to keep a clear picture.

Some useful suggestions from personal experience:

  • Preparation is the key. Be well prepared for the next meeting with your delivery manager and have your list of queries ready. As this was my first assignment as a lone writer, I did not hesitant to ask some silly questions also.  Get a good visibility and scope of your assignment.
  • Sharing and transparency are absolute winners.  Keep sharing regular status with your reporting manager.
  • Know your performance. For a new TW it is good to seek feedback from your reporting manager, not just on the document that you prepared but also about your pace and work style.  It assists in planning further and some areas of improvement might crop up.

It’s beyond doubt that working a lone writer one gains many insights and maturity as aTechnical writer, This further builds up confidence to work single-handedly.  Initially the trail proves a little difficult to crawl but finally one learns to walk.

Understanding Technical Writing

This is my first post and I could not resist the temptation of starting my blog with the most predictable and customary question. So here I am in my maiden attempt to understand the meaning of Technical Writing.

Technical writing, in general means to present technical information in a user understandable form to a selected set of people, like the user manual that accompanies your water purifying system or the manual that is handled to you while you board an aircraft.

Technical Writing is a sub branch of Technical Communication and as diverse and broad is the field of communication, same holds true for technical communication.  So, from writing documents  to creating user oriented information using various audio-visual aids like graphics representations, software simulations, video-audio instructions to transmit crisp and precise information for software or a machine falls into the category of Technical Communication.

The aim of technical writing is to help users identify, familiarize with a new product, making life easier for them.  Technical documents are also an important tool to help users in troubleshooting a problem, it acts a knowledge base, while people may seek guidance for a particular problem or feature in the product/application. Technically written material also enhances user productivity.

Sometimes people new to the field of Technical writing may confuse it with Technology writing. Under such circumstances it is even more important to develop a clear understanding of Technical writing and its nuances. Some of the distinguishing features of technical writing include:

  • Clear and concise communication
  • Simple and crisp language
  • Use of active voice
  • Writing in present tense
  • Short sentences
  • Technically accurate and validated information
  • Adhering to standard rules for instruction and procedure writing

These characteristics help to differentiate technical document from an article that describes the latest gadget and its features.

Few examples of technical writing are may help further.

The installation manual, the user manuals or the manual explaining the working of the solar cooker refer to as technical documents, whereas the manual about the product features, significance, advantages is not classified under technical writing.

On the other hand, medically qualified professionals use the operator’s manual of medical devices such as a MRI scanners. Such a manual qualifies as highly technical document and is intended to use by a skilled professional only.

If you are a software developer, the programmers guide or the API guide that you refer are also examples of technical writing.

History

I am on Twitter

Advertisements