5 Golden rules for writing technical documents effectively

I am neither the first one, nor an exceptional writer to talk about writing rules. In fact, there are plenty of better writers than me who have elucidated this perfectly. This post is inspired after receiving a lot of feedback from my editor. These are MY golden rules for writing effectively and I intend to print them and paste them on my cubicle wall.

Writing effectively means writing in a manner that the reader does not struggle understanding what you have written. As technical writers, we write a lot of things such as e-mails, user documents, API documents, and so on. After a lot of hard work (or hard words from the editor) I have designed these 5 rules that I use, or must use to write effectively.

1] Expand abbreviations

Though this might seem as a simple thing, it is important to understand why I consider this as Rule 1. We writers spend a lot of time with our product and documentation. We constantly interact with team members and start using their jargon. We are so akin with the product, team, and its terminologies that we no longer think it is important to follow the basic rule of technical writing – Expand abbreviations when you use them in the document for the first time.

We document in a wiki, for us, this rule means doing this on every single page. It is tiresome. But when you put this against a simple logic that a reader might land on any page in a wiki, and that becomes Page One! So, expanding abbreviations is important.

It is not just about abbreviations. When you internalize this rule, you will realize that this is required to avoid ambiguity in the documentation. Instead of just looking at abbreviations, our text should strive to avoid any kind of ambiguity that may confuse and mislead the reader.

2] Make screen elements bold and uncertain elements italics

Or, to cut a long story short – Apply correct font treatments.

Now, this is an area of concern. Before joining the company, I use to refer to Microsoft Manual of Style for Technical Publications (MSTP) – the universal style guide. According to MSTP, we should make all screen elements (GUI elements) bold. Unfortunately, my company does not follow MSTP, which means, I need to unlearn a few things and learn new rules afresh.

What I really mean to say here is, follow the style guide. Dot the i’s and cross the t’s. Trust me, it is not as easy as it seems and I still fumble with a lot of formatting guidelines. The only benefit is that I have a meticulous editor who keeps me in check (sometimes I actually feel she will mark my docs with a red penJ).

3] Match the GUI

Now this is a Universal Truth. There is no room for argument. Whatever is on the Graphical User Interface (GUI; my editor will be so happy!) must be shown as-is in the document. If you have incorrect spellings, bad grammar, wrong usage, the only place to correct it is the product itself. Do not be a saint and clean everything in documentation. You will only end up confusing readers.

Remember the time you couldn’t find that particular check box on the screen when you consulted a help document to upload pictures on Facebook? (OK, I know I exaggerate while citing examples! Don’t your eyes, please)

Did I mention this is a MUST-TO-DO rule? Doesn’t matter if it comes at a third position, this rule is seriously meant to be considered.

4] Write in an active voice, use short, simple sentences

Tell me you all do this already, please.  Strange how simple, and silly such rules seem when we are citing them. However, it is not so easy to be simple.

Write short sentences. Do not eat words. Stop using adverbs unnecessarily.  Write well.

Inculcate the habit of minimalistic writing. You will go a long way, not to mention, your readers will thank you. Really, I am not lying.

5] Make judicious use of words

I had to use the Thesaurus to see what exactly does “Judicious” mean?

Small things matter. Word choices can sometimes be one of the crucial choices you have to make.

When in doubt always consult the experts and write well.

These are my golden rules for writing effectively.

What are yours?

 

Marshmallows show the way

English: Marshmallows (Photo credit: Wikipedia)

I lost in the Marshmallow challenge today; I won the key to collaborating effectively between teams.

Marshmallow challenge is a game played to understand team dynamics, collaboration, and solving problems in an agile environment. Marshmallow challenge was a lesson in experiential learning today.

When we stepped in the meeting room today, we didn’t know or expect to learn something so good, so quick. When we entered the room, we were sitting in the groups of four. In front of us, on the table were the following things:

• 20 spaghetti sticks
• 1 mt. sticky tape
• 1 mt. thread
• 1 marshmallow

On the screen, a warning was projected – DO NOT EAT the marshmallow! Our trainer welcomed us and gave us a simple task. He asked us to do the following:

“Build a tower out of the material provided in front of you in 18 minutes. On the top of the tower, you must place your marshmallow. At the 18^th minute, step away from the structure and the marshmallow should remain on the tower for an entire minute. The team that builds the highest tower and whose marshmallow stays on the tower for an entire minute, wins. ”

Easy, right? Well, we were gonna find that out soon. We spent the first 6-7 minutes in planning. We thought planning is important, right. Everything requires a planning. So we formulated a plan. We decided to build a base for the tower, that’s important, by cutting 4 sticks of spaghetti in 4 pieces each. We stuck them together to make a base. Then we used 4 sticks and pasted them on the base. We pasted the point where all 4 spaghetti sticks met and thus created our first level. Then we used another 4 sticks and pasted them with the base tower. On the top, we created a triangle out of the small spaghetti sticks and decided to place the marshmallow in that triangle. Something like this:

Spaghetti tower

Like you can see in the picture, we were not successful. The tower kept on reclining due to the weight of the marshmallow and that’s the reason my team member was holding it with her hands. There were 6 teams and out of those only 1 team could manage to get the marshmallow to stay on the tower.

After the game, which lasted for good 30-35 minutes, we watched a video by Tom Wujec on Build a tower, build a team. This was the case with almost all the teams. The team that won, somehow managed to get their marshmallow stay for a minute and the next second the entire tower collapsed. After spending 30-35 minutes playing this game, we watched a video by Tom Wujec that unraveled the Marshmallow challenge and its relationship with building teams.

TED Talk: Tom Wujec: Build a tower, build a team

It is a fascinating video. In less that 7 minutes, Tom explains some simple concepts that we are aware of usually, but throw away to caution the moment we think it is just a game. He talks about being agile, being able to work together in a team, understand the problem, find solutions with existing resources, implement and test the solutions, and being innovative while doing all these things.  He talks about how every member in a team brings something from her own experience to the table, how each member’s contribution is important.

So what did I learn from the Marshmallow challenge? Here’s an outline:

1. Each element in the team is important.
2. Everyone brings something to the table from their previous experiences. It is important to listen to others when devising a solution.
3. Checking reality from time to time always helps. Keeping a track of time is important as well as checking the requirements.
4. Prototyping is a must. If you have seen the video, you will find astonishing results about the kind of teams that won, their age group, their attitude, the education that made them the winners.
5. Teams who test their solution at every level, have a better chance of delivering a workable solution in the end.
6. As much as we are allowed to soar high, our base should be solid, perfect. Only then can we deliver solutions that do not topple down in the end.
7. When time is scarce, we need to think quick and start working immediately. Long periods spent in planning the project end up reducing the time for evaluating and testing our implemented solution. Just do it!
8. Uncooked spaghetti does not taste nice

I take these lessons from the game, you may infer differently. However, we must agree, these were the best 45 minutes that I spent in any meeting learning something new.

Theater in technical communication

This year started on a good note. I started doing different things than expected at my workplace. One of them was to act in a drama. A bunch of enthusiastic people came together and put up a play that we performed in a competition. The competition was also one of its kinds. It was hosted by the Project Management Institute and the theme was – Theatre in Project Management.

We presented a play based on the recent UID scheme, popularly known as the Aadhaar Card scheme implemented by the Government of India. The plot was centered around considering the Aadhaar Card scheme as a project implemented by the Government, identify gaps at the planning stage and at the execution stage. We stopped at identifying gaps and then the main character summed up the situation and gave advice to resolve all this in the last 4 lines. The lines were taken from Hindu Holy Text – Bhagwad Gita. Literal translation describing the essence of those 4 lines is:

Before you begin with a project, take all stakeholders in to consideration,

Study the obstacles in your path and then take the boat across the tide,

Prepare a schedule and stick to it diligently,

There are no guarantees in life, know it when you start any venture!

 

This is a crude translation however, the essence of these lines is important. Even more important was the experience of being a part of a play. Something I had never done before for the simple reason that I thought I cannot act or I will make a fool of myself.

This exercise taught me a lot of things and here’s a couple of lessons learnt:

• We worked a lot on the script before moving on to finalizing the characters and the actors that would play the characters. We had approximately a month to prepare and almost 2.5 weeks were spent in writing and planning the script. Once the script was ready, we practiced and got the play up and ready in just 10 days. It shows that if adequate time is spent on planning, execution becomes relatively simple. I attended a topic analysis session recently, and the speaker kept on insisting that the amount of time spent in topic analysis was inversely proportionate to the time it took to write/document the topic.
• The language we used was Marathi – a regional language. While we knew a majority of audience would be well versed in the language, the fact that it was an IT competition in a city that has companies that employ people from all over India should have been taken into consideration. The group that won the prize presented their drama in Hindi. While this is not the sole reason why we did not make it to the finals, this could very well be one of the reasons why we were left behind. Language, jokes, references to personalities, literature etc. should be relevant and understandable by people who see our play. In technical communication, we write for the audience. We must speak the language that our targeted audience would understand.
•  It is important to start and end the play in a manner that is well-received by the audience. I think we took off on a good note and ended on a sound verse too. The start and the end should be in sync with the theme of the play. Only then does the audience connect with the play. An abrupt beginning can be detrimental.
• Throughout our practice sessions, we were asked to speak slowly, enunciate at the right words, right places, modulate voice to express emotion. These were all tools required to ensure that our words, punches reach the audience.  Use all the tools, but sensibly. Do not be melodramatic. Do not over punctuate, do not cram a page with images just because you can.

Well, these are the things I learnt from theater. This post is actually inspired from a video one of my colleague, Hemant made.

 

Want to increase your productivity at work? Work from home!

My company is one of the few ones who allow its people to work from home. I am not a huge fan of this for several reasons, which I will elucidate further in the post, but what I have prominently noticed during the occasional “work-from-home’s” is that it is a complete productivity booster.

Here’s why I think WFH (as we lovingly call it in my company) will increase your productivity:

• WFH work’s best if you are alone at home. If you are alone, you will talk less to people, concentrate more on your work and end up doing quality work.
• When you are at home, you are not distracted by the random conversations that occur between people sitting in the same cubicle, you do not greet people at work when you are at home and hence, no non-required chats. This ensures that you stay focused on your task.
• You also have a choice of starting the day early (like I did today, at 7:30 AM) and work in the best hours of the morning.
• WFH also ensures that you take a break when you want, not when someone asks you to join for breakfast, or lunch, or coffee at the office.
• It is a best way to work if you want to finish tasks that require individual effort and not team collaboration.
• WFH keeps you happy, as you have the flexibility of working hours at your disposal.

If these are the reasons why I prefer working from home, I now would illustrate the reasons why I wouldn’t really want to work from home for a longer period:

• I do not like to work in isolation. Even when I am given individual assignments, I prefer working from the office as I get to interact with other people.
• WFH also means I am tempted to finish off any house hold chores that are pending and that can seriously set back my productivity charts. I can ignore a sink of dishes when I am in office, but at home, I will always think of doing those first before beginning the next task.
• Even if there are no people to distract, the very fact that you are “at home” can be a distraction. We tend to be relaxed at home and with the office environment missing, you might end up being too relaxed.
• If you do not have a good setup at home for you computer and work station, you might not be able to focus more as uncomfortable seating positions do not help in increasing productivity.
• “Work from home” can also lead to “work for home”.

If you are the types who works best alone, the WFH is a good option. However, for people like me, who want to be surrounded by others, would only prefer it once in a blue moon.

Articles I read that made an impact:

• http://www.zdnet.com/blog/btl/trying-to-increase-productivity-send-your-employees-home/10336
  
• http://newsroom.cisco.com/dlls/2009/prod_062609.html
• http://www.forbes.com/sites/stevecooper/2012/08/31/boost-productivity-by-working-from-home-really/

Future of Technical Communication

Somebody asked me today, what do you think is the future of tech com or technical communication and it snowballed into this post.

Source: http://www.oldthinkernews.com/2010/12/5-futuristic-technologies-ibm-says-will-soon-be-a-reality/

What is the future, really? Is the future in graphics, the way Ann Gentle sees it? Or it’s in videos? Is it in the interactive graphics, gamification, wikis, social media, user-generated content, and so on. No, this is definitely not the future. For each of the ideas shared here I can already point to people and companies who are doing it. This is the present, not the future of TechCom.

So what’s the future now? Is it an in-built, all pervasive help in the form of effective user experience within a product? Or should we be radical yet again and say we will create products that won’t require help or a user manual at all? Oh that’s every developer’s dream ever since we had a phenomenon called – Steve Jobs, but the fact remains – only one Steve Jobs, only one Apple Inc.

We talk about innovation in TechCom, but now, what’s left?

That’s a nagging question I haven’t been able to find an answer – What’s the future of Technical Communication?

It’s that time of the year…

When the promotions are declared. It is that time of the year when payouts occur. It is that time of the year when someone is thrilled because she is just being promoted. It is that time of the year when someone is planning to quit the company after a major disappointment. It is a time for evaluation and feedback. I have done my part, I have written and submitted my self-evaluation and I am awaiting feedback from my manager. I am a realistic person and I know I could have done much more in the period so I am not really expecting a great reward.

What I do expect, is an honest feedback. I like people who are honest with me. I would really prefer a manager who tells me I am not performing as per her expectations than somebody who praises me unnecessarily and that does not reflect in my payout. That brings me to another question – What do we consider as a reward for our work in a particular company? Is it based on how much salary or incentives I get, what kind of role do I get to perform or something else? Do we really ever think about it when we decide our goals right in the beginning of an evaluation period?

So here’s what I plan to do for my next evaluation period, irrespective of what feedback I receive:

1. Set clear and realistic goals after discussing with the manager and identifying the areas of improvement for me.
2. Add a plan of action for each goal, preferably with target dates.
3. I already have a mentor, I intend to take her help in discussing my strengths and weaknesses and improve them.
4. Ask for regular feedback.
5. Turn actions into achievements.

If I stick to what I have written here, I intend to achieve measurable progress in some of the areas in the next few months. What motivates me is the common goal of the company – Enhancing Customer Experience. The common goal for the company is the common goal for me. Here’s what I expect from my Manager:

1. Set my expectations clear.
2. Give honest feedback on where I stand, does the company value my contribution or I need to work on some areas.
3. Show me the ways in which I can enhance my skills and overall performance in the company.

Like I said, this is what I intend to do. I do not know whether I will be able to do it.

 

Disclaimer: “I haven’t been promoted, nor been promised a hike, and thankfully not demoted either. I am not some rich snob and I do care about the remuneration I receive. I am just not a person who spends a lot of time complaining. I either do something about it or move on. Also, I do not even want to offend anyone’s sentiments by writing this post. It is a reflection of my thoughts and nothing more. “

 

 

Never Stop Learning

I was a part of a project, documenting an entire product, on my own. There were hardly any documentation processes, no clearly defined guidelines or anything to help me write. I was a new writer back then, maybe just a year old in the technical writing industry. I used to stumble upon a lot of things. There were loads of decisions to make. Should I be documenting everything the product can do? How do I make a 500 plus page manual easier to read? Do we need online help? If yes, what tool, what format will be better for an online help? Should I be making some marketing material? These and many more questions were in front of me. Till then I was unaware of making the optimum use of the best tool I had at my fingertips – Google.

I won’t tell you how I reached here or what I went through when I first stumbled upon blogs written by Technical Writers. I will simply describe the experience as an epiphany.

There were zillion technical writing blogs that I read in that period. I learnt from the experiences of other writers. I asked questions, got them answered. I experimented with my work. The major influencers were Tom Johnson, Craig Haiss and Ben Minson. Their blog posts were a reflection of what I was going through. Craig Haiss wrote a lot about the basics of documenting user manuals, Ben Minson wrote about online help, and Tom Johnson has an entire series on developing Quick Reference Guides. I made quick reference guides for each application in my product and they were a complete hit. I also read a lot of blog posts by Ugur Akinci to understand the basics of technical writing.

The point I am trying to make here is that the problems I encountered pushed me into reading a lot of things online. I consider all that reading as a part of learning as I not just read, but also implemented a lot of things. Some stuck with me forever.

What is professional growth after all? It is an ability to change and adapt to the new world. When you have an inclination of learning, all things around you teach you something.

There can be two kinds of learning, either you attend some professional courses or you do self learning activities such as reading blogs, news, etc. online or joining social forums that are related to Technical Writing.

Attending professional courses will not help unless you are ready to invest that kind of money and your time into it. At the end of the day, you should benefit from the course and be able to implement what has been taught. I am not a big fan of academic courses as I have not done any that will help me in my current role. I am not discounting the value of such courses. I just haven’t come across something helpful yet.

When I talk about never stopping learning, I mean learning by yourself or with a focused team.  I have partnered up with a colleague of mine, with whom I share the same wavelengths and get along very well. We spoke to each other for 6 months before starting a project all by ourselves. He is my professional buddy. We talk, we read, we inspire each other and we learn. We also bring back what we learnt to our daily lives. We have realistic goals and measurable results. But sometimes we throw away all standards and just do what we want. We learn through sharing, we learn through discussions, we learn through debates and we learn just by interacting with each other.

My tuition teacher in class 10 was a 70-year old man. He bought a computer at that age and learnt how to send emails and use the computer. There were many people who asked him what he wants a computer for? He only said that he wants to learn!

Learning is a never-ending quest. Keep the flame alive and keep on learning new things. It’s never too late to start.