Relevance is the Key

It was a busy week for us. Amidst the lockdown and the pandemic, we managed to see the doctor adn got our medical certificates done. Then, over the weekend, we traveled to our hometown. I did all the planning, packing, and traveling to and from the hospital in the work breaks. This helped me manage the work, meetings, and other priorities. But the writer’s brain continued to work as usual, and thoughts continued to spin their web. So came this post.

While creating the guidelines for writers in my team, I realized how important it was to write crisp instructions. The guidelines were for reference. But most writers would go to the wiki not before, but while preparing the content. They would be more productive and busy in writing their content than digging into my referential one. Relevance was the key.

And, based on the little head pounding that I did on the subject, I zeroed-in on this:

Contextual Relevance

The profession of writing is an interesting one, for it teaches us more re-writing than writing. Staying true to the context is, therefore, second nature to us. You will not find a single sentence that doesn’t serve the purpose, the core, the topic. There could be more than one sentence to stress the importance of the point.

When creating the content, I reckon that we focus on writing about what the readers are searching for. We must write about what leads the readers to look for. We join context and content: the resolution to their problems, the remedy to their pain, the destination to their journey of searching for information.

Emotional Relevance

How empowered was the reader after going through your content? Could they make a decision? Could they press the button? Did they feel as empowered as you wanted them to? Or are they still looking for something they thought after looking at the title of your content? Ask yourself questions like these. Check your content to see the possible impact of it on the lives of the readers. One of the results of your writing the content is empowerment. Ensure that readers feel confident after going through it.

Strategic Relevance

Your content should help them see the whole picture in a logical sequence. The readers have embarked on a journey, remember? So they are entitled to see from where they have come, where they are currently, and to where they may lead. The clarity of steps is the clarity of mind, at least in the context of instructions.

Critical Relevance

Just as important as it is to know whether or not to press the button, it is equally important to see if it would solve the problem or lead to the next step. Instructional content is seldom laid on the same foundation as that of creative writing. That’s because creative writing doesn’t always have to deal with the What’s-in-it-for-me question. So the result of instructions is a definitive outcome measured in tangible or intangible results: it could be pressing that button or reaching the end of the instructions.

Conclusion

Yesterday, while talking to one of my ex-teammates and long-term friends, I shared some ideas on how they could get started with their work. I told him that one of the best ways to learn was to teach.

I just realized that the inverse of it is equally true, too. One of the best ways to teach anything is to learn to do it. And while I will continue to polish the writing and editing guidelines and add more reference-worthy points to it, I will continue to keep things relevant.

There aren’t many ways in which technical writing and creative writing differ, but for want of the outcome of actions. Relevance is critical when it comes to measuring the result. Isn’t it?

Top 3 Tips for Writing Crisp Sentences

My friends often email me seeking help with writing. This post adds to the reply I gave to one of my friends who asked:

What should I look for to construct better sentences?

I assume the question relates more to work-related writing (jotting thoughts down) than speaking. So, I am slightly changing the question to fit it as the topic for the post. 😊

Here are my top 3 suggestions for writing better sentences:

Tip 1: Give Action Points

Whether it is emails, meeting notes, Sprint retrospections, or a web chat with a colleague, clarity in communication is of the utmost importance. Be clear with what you wish to say. Write, then read (and, if required, re-write). Then, send. But, please mind the gap; there is a difference between being straightforward and being offensive.

Tip 2: Use Active Voice

Consider that Ram is preparing meeting minutes. This is what he writes as an action item:

Inputs on project estimation must be given.

See how he skips mentioning the doer in this passive sentence. That’s usually with every passive sentence. Let us rephrase this to introduce active voice (and hence the doer):

Shyam needs to give inputs to the PMO for project estimation.

See how sentences in the active voice clearly define responsibilities? Had Ram circulated an email with a passive sentence, we wouldn’t even know Shyam was supposed to share his inputs.

But, should we always construct sentences in the active voice?

No. In cases when you generalize or do not have any recipient for actions, you may use the passive voice. For example:

The velocity improved for the Sprint.

In this case, because the velocity improved for the entire team, we are sure that each one of the teammates contributed more. You may also use the passive voice for highlighting facts and figures. In the same example:

The velocity improved by over 5% for the Sprint.

Also:

An average of 5% capacity is reserved for holidays.

(Considering reservation of capacity to be a known item for capacity planning.)

Tip 3: Remove Needless Words

There are words that do not add to the meaning or intensity of the words they accompany. For example, “very” and “really”. However, approach this tip with caution.

Consider this example:

This cake takes very good.

We might as well get rid of “very”, and the cake will still taste equally good. But, by no means should you take this as a rule of thumb for deleting all occurrences of “very”. The very purpose of “very” (pun intended) is to intensify something that already exists.

If, however, there is a rule of thumb, it is to seek brevity. Look for opportunities to shorten or, at least, vary the length of your sentences. This means you give the reader more opportunities to flow with the rhythm of the words, take sufficient pauses, and contemplate on what they read.

Bonus Tip: Listen to Your Mental Ears

I really like such sections—another exception to Tip#3. Readers would usually jump over to this section first. If you too did just that, welcome aboard. As I share my top 3 tips for writing better sentences, I see that most of us already know the tips. The problem is they don’t know how to put that knowledge into practice.

How do we identify what and when to change?

I’d say listen to your mental ears. They are never wrong. You can always check for the meanings of words or phrases you are not sure of. Look at your write-ups the next day. Take a print out and read out loud. Project the write-ups on a bigger screen. Let someone else read your write-ups out loud to you. Take a break and re-read your write-ups. There’s a lot that can come in handy. But, nothing beats the joy of rewriting. Before I release my posts, I write and rewrite them in the proportion of 1:4.

Conclusion

Let us revise:

  • Enlist actionable items. I just did that.
  • Use active voice, but don’t be offensive.
  • Remove words that do not affect or contribute to the meaning of your sentences.

Sub-topics like “varying lengths of sentences” demand a post of their own. We can even experiment with including a combination of words that produce lyrical or homophonic composition: “she sells seashells”.

To sum up this post, here’s what I have: it all depends on finding the sweet spot where meet relevance and comprehension.

Happy writing.

Contribution to STC India Annual Conference 2018

Since the last few years, I have been regularly contributing to the STC India Annual Conferences.

This year though, I was loaded with work. After I gave up the co-editorship for Indus, the STC India chapter magazine, I could free up some schedule for the blog. So, I could schedule articles and posts beforehand and be more active on my blog (site).

Late November, about three days before the release of the newsletter, I received a request to write an article for this year’s Annual Conference’s newsletter. Of all the time I was given, this is what I could manage.

I am happy that my article fits well with the others. And, happier, because I could deliver within the given time. Hope you too will like reading it. 🙂

From Micropoetry to Tech Comm: Connecting the Dots

In only 2015—quite recently, I know—I learned about Haikus. But, it took me three more years to begin to understand Haiku and the other forms of micropoetry. You might have read some of my recent experiments with writing micropoetry—like this and that.

So, this post is about the insights that micropoetry shares with technical communication:

  • Sometimes, a lot of solitary moments teach you more than an experience that lasts for a length of time. Micropoetry is one such experience of wisdom that lies within a moment. It is either result- or experience-oriented because each word or line carries an action or empathy.
  • This one matches the Pyramid Approach in technical communication. We communicate the most important information first; everything else Similar goes for micropoetry, just that there is no “everything else” in this case.
  • Words count; count the words. Usually, the lesser the better. Simple.
  • Words weigh based on their definition. Word also weigh based on the intention with which we apply them within a sentence. The latter is the reason people perceive the same word differently in different situations. So, for the sake of the composition, we must keep the right word in the right place.
  • Stories move us. Stories empower us. Stories educate us. All three apply to micropoetry and to technical communication alike.

What are your thoughts? As always, I am curious.

Don’t Redesign

Yeah, you read it right.

How many times have you seen me make changes to my site’s template? The last time I made those changes was about a year back. I made the design simpler and more readable. Or so I thought. My mom found it difficult to locate her favorite articles on the blog. For long, she would navigate to them from the dropdowns that I have now done away with.

I know exactly what you are thinking. Unfortunately, revamping the look ‘n’ feel hasn’t improved the inbound traffic. The new template has only improved the presentability. So, it is now easier to categorize and tag the released posts by month and year. But, it makes it horrible for repeat readers—like you, there—who wish to select, search for, or read content they liked. Does that mean people hate change?

Yes, people hate change; no, they don’t.

Those of you who are new to my site MIGHT find the new design easier to navigate. But those who have spent time with the content might reject the outright changes. Familiarity is the word in context. It is just that the design had become a part of your physical and mental memory. For repeat users, they knew what they wanted from the content, they knew what I delivered, and they knew how to get to it.

For you, too, slamming on a new UI might ruin this flow for your readers, who are then more likely to take more time to locate something.

So, what’s the way around?

Here is the trick: familiarity trumps functionality. I have stated this in my book, too. If you wish to redesign, consider first reconfiguring the core design. Your design is purposeful. All you need is reconfigure it.

In most cases, all you need to do is progressively improve the things under the skin, rather than get a new skin. I find it to be a Win-Win. Bring a new change under the hood. This means the consumers get a familiar UI, with performance tweaks as perks. And. you get a chance to rollback if (and when) required. It takes time to take effect. But, it is a better approach.

Happy writing.

Be Content with Content

Be Content with Content

I would be amiss if I were to begin without defining the word content. That’s because it gives both a purpose and a premise to the topic: being content is feeling satisfied with your possessions or situations. But why this play of words in the title, you may ask. Here is why I rant…

Let us go back in time. Not far back into the world of typewriters and hand-written manuals. A couple of decades ago: when the concept of single-sourcing originated. I hadn’t joined the technical writing workforce then. Back then, the requirements were simple: get a single-sourcing tool to create everything from within one source. Then, use that source to generate the content for all formats. A lot has changed since. Yet the idea is to have a single repository generate the content. Just that we have complicated the process of creating and managing that content.

When I first single-sourced my product’s contents, I felt the need of creating a central repository for storing and generating the content—the likes of PDFs and CHMs. With that was born my organization’s server where resided the content. But, my requirements didn’t stop at that. I continued to remodel (or so I thought) my work processes to redefine the way I maintained that content. Then came XML, which helped me to tool-proof the product’s documentation.

Who knows, someday I may even put my head into Application Programming Interface (API), Internet of Things (IoT), and others. Did you notice how the story is becoming more about the tools of the trade than about the traded content? Sooner or later it will be about some other “hot” technology. As I continue to choose a (better) combination of tools and methodologies, I continue to steer farther away from the focus on the content. This could be your story, too.

Progressive and Cyclical User Requirements

User Requirements are Progressive and Cyclical

A side note: a seamless user experience is easier to put on to paper than to put into practice. Agreed. Also, agreed that these days we have tools that we can use to instantly connect with our users. So, we can know which sections of our documentation get the most views. Or, which ones are the most or the least helpful.

From where I look, tools and methodologies originated to save our time and effort. But now, it looks like we have lost ourselves in managing them rather than the content. Let us not focus only on creating a content-management ecosystem. Instead, let us create a problem-solving ecosystem. Let us not forget that the users’ requirements are progressive and cyclical: the target for usability changes frequently.

It all starts with answering “why” and ends with exploring the answers for “what’s next”. Such content that continues to bridge this gap of “why” and “what’s next” is truly satisfying. A tool will only enable us to create quality content. It isn’t an end, but surely a means to an end. Let us solve users’ problems and be content with (the focus on) content.

The Question of Approach: One vs Many

The Question of Approach: One vs Many

Last week, for our internal communicator’s club meeting, I presented some Tips for Effective Writing. Those who attended the session were mostly developers. And, that’s why it was even more useful for them. To help understand the core need for communication, we used a picture quiz, which you and I will discuss through this post.

Look at the following pictures (courtesy: Internet). The first picture is of Lotus Temple, New Delhi, and not of Sydney’s Opera House. The other picture is a multi-utility tool, also called Swiss knife. Here’s a question for you:

How do you think the two pictures contrast?

Before you begin answering the question, here’s a little built up for it:

As a seeker of information, I am like every other “user” or “audience” – I am like YOU, dear reader. I prefer to take the shortest or quickest path to the resolution. Much like you, I get petrified when I can’t find the shortest route. Much like you, I get petrified when I see unorganized or insufficient information. It’s as simple as that. This puts a lot of responsibility on the shoulders of technical communicators and user experience (UX) designers. Sadly, there is still no guarantee that we, the information seekers, would access the right information tidbit at the right time; or even if we do, we get to use it correctly. This means, despite all efforts by technical communicators and UX designers, the communication remains incomplete if the seekers can’t get to – or comprehend – the right information or the right tool at the right time.

Given that background, look at the first picture.

 

Lotus-Temple-Aerial-View

The Lotus Temple, New Delhi

 

Here is the message from the technical communicator within me to the information seeker within me: those who seek answers to oneness and peace, go to Lotus Temple. Don’t drift: the name is indicative. So you can take any temple, mosque, church, or even faith. Seekers like you might have a lot of questions, but each of those questions will lead to only one answer: of realizing the seeker’s true self. So, there may be numerous problems that might lead to just one solution. This resembles the Sanskrit hymn, Ekam sat vipra bahudha vadanti, which largely translates to “That which exists is One. Brahmin (Sages) call it by various names.” Rather than seeking the solution, seek for what you wish to solve – the need. That’s how even I have organized the content for you.

Look at the second picture.

 

victorinox_mountaineer_lg

Multi-utility tool

 

Here is the message from the technical communicator within me to the information seeker within me: those who wish to complete a task or resolve their issues will seek such a tool. A tool, which has one unique solution for every problem. A tool, which can do a lot, but only dedicatedly. Seek, if you must, the need. The tool is still only a medium to accomplish; it’s a means to achieve, not the end.

But before talking about contrast, let us take a minute to discuss a little about what’s common for both the pictures. The only common thing is the need. The need to discover, resolve, and accomplish; the need to get things done; and the need to get questions answered.

So, here’s the contrast: the contrast is in having one universal solution versus a unique solution for every problem. The contrast is also in stressing the presence of the right information tidbit and of the right tool both at the same time. For the seeker’s shortest route to the resolution is the one that contains a quick and unique solution to their problems; the one that addresses the need.

What’s the lesson for the seekers and technical communicators?

The rules of grammar stand true and remain unchanged. However, there still are different ways in which we can compose, express the same information. Similarly, even though there are style guides and standards, there are hundreds of scenarios that we can count as exceptions. Probably, that’s why we see the Microsoft’s Manual of Style, fourth edition, mention “Microsoft” and “Not Microsoft” ways of creating content, unlike the “correct” and “incorrect” ways in their third edition of the book.

We should choose based on what’s needed, required from the content. There lies harmony where both technical communicators’ and information seekers’ needs meet.

The Write Stride: A Conversation with Your Writing Self

The Write Stride: A Conversation with Your Writing Self

My first book on technical communication is available for pre-orders on Amazon. Secure your copy today and save 20%. The book releases on 6 June 2017.

FB Profile Page - The Write Stride

Credits:

What’s the Difference Between Book Blurb and Synopsis?

What’s the Difference Between Book Blurb and Synopsis?

As I ready my book for its release, there are a few things that everyone tells me to do. Two of which are to write the book blurb and synopsis. This post is for those who confuse between the two, much like I once did.

For those who are rushing, here is the gist: Both project the book to different sets of readers. So, the simple difference is that a book blurb SHOULD NOT contain the conclusion because it is your book’s sales pitch, while a synopsis is a 200-word version of the book itself. Think about suspense, drama, and questions when you are writing a blurb for your book. But, give one-sentence answers to those questions in your synopsis.

Here’s the elaborate version:

What is a Book Blurb?

A book blurb is your way of selling your book. Like the book cover is one of the biggest selling points for any book, a book blurb helps sell the idea of the book to those who are in search of reading something either new or out of their usually picked genres.

There is one big difference though between a book blurb and a synopsis. A book blurb does not include the ending. Your fans, readers, and prospects wish to read your book. You can make it more exciting by raising some questions without giving away hints about the answers. Through the book’s blurb, you can give an idea about the plot and about why is the suspense/flow of events bothersome/intriguing, but do not let the ending spill out to the prospective readers. This drama is enough for them to make the purchases. But what do you do if you are writing a nonfiction because you can’t use drama, for sure? In such cases, you can use questions; questions that intrigue the readers; questions that make them think; questions they had, but could never answer.

What is a Synopsis?

Your publishers get hundreds of manuscripts every day. So, if they would read each one of those, they would take a lot of time to finish the publication process. Your synopsis makes the job easy for them. In simple words, a synopsis is telling “what’s your story”.

Like we discussed, the book blurb does not contain the ending. But, the synopsis should contain not only the gist of your story but also how things conclude. If it is a work of fiction, tell the publisher how the protagonist brings the bad forces to justice. If it is a work of nonfiction, tell the publisher how you as a protagonist bring off things, or so to say.

Tell the publisher who the protagonist is; about what challenges the protagonist is confronting; about why it is the time for the protagonist to prepare for and face the battle of their life; and, passively, about how facing challenges makes living worth it.

There is one important point for you to consider. Follow the tone of your work. If it is a work of fiction, follow the tone of your novel. Be romantic if your novel is about love, romance, and togetherness. Be funny if your novel is full of humorous incidents.

Why does understanding this difference matter to me?

I want to sell my book. I want everyone to appreciate what I’ve written; not because I have written it, but because their reading it will make a difference to their lives. I want the readers to acknowledge my addressing some of the questions they have had. And, because understanding this will help me create content that addresses the right audiences rightly. Words matter. And, so does the impact they create.

Happy writing.

Are Technical Writing and Instructional Designing the Same?

Are Technical Writing and Instructional Designing the Same?

This post originates from a couple of related question that I answered on Quora, which you can find here and here. For those who are rushing, here is the gist of the post: Although I don’t regard technical writing and instructional designing different, I do acknowledge that the tools and methodologies both use are quite different.

For the elaborate explanation, I resort to breaking the big question in parts:

How are technical writing and instructional designing different?

Howsoever thin, there is a line that separates technical writing and instructional designing. Yes, I agree that though the end-result is still similar, the routes taken are different. And, here is the first difference. Technical writers focus more on collecting, collating, and presenting information, while instructional designers focus on streamlining the correlated tasks into stepped instructions and courses. Another difference I see is in the approach. I always say that technical writers are backstage players. No one knows they are there, but they are. And, unlike instructional designers, technical writers can never become the front-stage players.

As a technical writer, I deal with creating and maintaining user guides, help files, and release notes, but if the time and scope permits I also get to write white papers, knowledge base articles, full-scope or abridged customer-driven metadata, and blogs. The goal, however, across all cases of documentation and complexities is empowerment. Instructional designing deals with information that’s both specific and generic. It does include offline or online learning, self-paced or instructor-led learning, and activity-based learning from simulation or gamification. The goal, however, across all cases and complexities is still on learning. But then my exploration limits my knowledge.

The thin line that differentiates technical writing and instructional designing becomes thinner at the object level. For example, when you create a knowledge base write-up, you focus both on empowerment and learning. You wish that when a user reads through your document, they will know what next to do and why. I can also see some rules that apply to both technical writing and instructional designing.

In today’s mobility-friendly world, people want everything on the go, including information. And, depending on what you seek or what you have (a smartphone, tablet, watch, or eyewear), the information complexity, language, and medium changes. This means that both information and instructions must be easy to understand and easy to use. In one way, this means fewer words and more visual content. But, we’ll discuss this some other time. Let us look at the second part of the big question.

Do technical writing and instructional designing require different skills and tools?

Quite rightly, the thin line of difference in the professions extends into the skill set and tool set as well. While it is true that both the skills and tools mostly are common, the percentage of a skill’s or tool’s relevance certainly changes based on the profession. I feel that technical writing involves more researching than instructional design. But, like I said, my exploration limits my knowledge. Instructional design involves more of storyboarding. So, it is good to assume that it will also involve more of action-driven, task-based sentences.

Both involve writing instructions, but technical writing restricts such instructions to stepped procedures in user guides and troubleshooting guides, while the entire storyboarding in instructional designing is task-based and action driven. Instructional designing is more of learning management. Consequently, you should have a better understanding of what users do with your products.

Let us take a small example. Consider that you have a job at a place where even a small error might result in huge losses for the company. Now, we will agree that the software or hardware products that you will get to use in such places will come with manuals. But, will it still not make sense for you to undergo a formal training before you get involved in your daily duties? I hope you can now see the difference. You limit your information goals based on your work processes and sequences of actions; on how a tool is designed to work and how it may fail; and, one how you wish to keep yourself and your peers safe and the work processes smooth.

In the context of the differences in technical writing and instructional designing, given the information goals you seek, it would be right to consider instructor-led training first followed by a regular check into the user guides wherever required. That should lend you insights into the only possible difference in the professions. Let us now address the last part of the big question.

As a technical writer, can I switch profession into instructional designing?

Either way, switching shouldn’t sound challenging; it wouldn’t be easy, for sure. But decide what you wish to do or help the users in accomplishing.

Conclusion

Before I conclude, let me take a moment to help you look at how I’ve understood this indifference. First I determine what the user wishes to accomplish. Then, I determine how they wish to accomplish their learning objective. Then, I look for the resources I could use to help them accomplish their learning objectives. Then, I break that learning objective into logical, sequential parts. Now, I see if I could create content that ushers them through those logical, sequential parts. The point is that I register the impact of each of those logical, sequential parts. I register the growth of user’s learning as they move from one goal to another and, eventually, one objective to another.

You see that the already thin line of difference between technical writing and instructional design further begins to blur.

Let’s just introduce a new word into our discussion: training. The word adds a lot of clarity in our understanding and helps us define the scope of both technical writing and instructional designing. Based on what we’ve discussed so far, can we say we are talking about technical training instead of instructional designing? If yes, can we say that technical training helps graduate a user’s understanding from one logical sequence to another or from one learning goal to another? And if that’s also true, aren’t we negating the difference between technical writing and instructional designing?

This is exactly why I don’t regard technical writing and instructional designing different. They may be two sides of the same coin, and I am OK if they are that way. But, that still doesn’t change the end-result for the users. Despite what users wish to peruse, they seek insights and accomplishment. And, as someone who enables them to achieve both these, I continue to remain a problem solver for the users. And, I don’t care what you name me as.