Tag Archives: Technical Writing

Don’t Redesign

Posted on by • Posted in Technical Writing • Tagged , , , ,

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

Posted on by • Posted in Technical Writing • Tagged , , , , , • 2 Comments

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

Posted on by • Posted in Technical Writing • Tagged , , , , , , , ,

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

Posted on by • Posted in Creative Writing, Technical Writing • Tagged , , ,

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?

Posted on by • Posted in Creative Writing, Technical Writing • Tagged , , , , , , , • 1 Comment

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?

Posted on by • Posted in Technical Writing • Tagged , , , , , , , , , , , , ,

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.

Which is the best and the most reliable technical content writing software for any technical content writer?

Which is the best and the most reliable technical content writing software for any technical content writer?

Posted on by • Posted in Technical Writing • Tagged , , , , , , , , , , , , , , , , , , , , , , , ,

I’d say that it depends on your organization’s standard processes, requirements, budget, delivery formats, and time at hand. I’d choose based on those points. The current trend is shifting from the conventional PDFs through videos, tutorials, and interactive help. But, based on my previous stints, here is the list of usually-used tools I’d say useful to you:

  • If you rely on instructional videos for your organization, you can use TechSmith Camtasia to create instructional tutorials, provide voice over, run parallel tracks for superimposing two faded screenshots, and provide animation and special effects, too. The other similar tool, which I find was equally easy to learn was Adobe Captivate.
  • If you are heavy on video reviews instead of instructional videos, you can look at other movie making videos like Adobe After Effects.
  • For those who still use the conventional PDFs, there is a plethora of choice available.
  • If you use single-sourcing and are keen on creating content that is reusable, I would suggest tools like Adobe RoboHelp (the latest version is just fantastic because you now can create Apps, too) and Help & Manual (this is perhaps the most underrated tool, believe me).
  • If you are following the DITA XML methods of structured writing, I’d suggest use Adobe FrameMaker. You could also use MadCap Flare
  • If you plan to create an online, Server-based, CMS-oriented repository of your work, I’d suggest you use Atlassian Confluence. First, there are a lot of plug-in applications that you can add to it. Second, this is a centrally-managed-and-organized tool. So, this means greater control on who is working on what. Another advantage is that you get periodic updates that get pushed into your system automatically. Just that some of my friends tell me that it is a little expensive to implement. But, since I haven’t used it, I wouldn’t choose to comment on it.

But, there is a lot more to deciding on a technical writing tool that just that. You have to decide on what software will you use in order to implement version controlling. Version controlling will help you create and post versions on a Server so that neither your data is lost nor there is more than one technical communicator working on the same thing. A software, such as Bitbucket (previously called Stash), SVN, and VSS can help you do that.

You should look into a bug (a.k.a issues) management tools like the JIRA. This is a complete tool for creating and managing items that need to be worked upon. You can add people to the item-specific conversations; cross-refer to other JIRA items; create sub-tasks; and drill up, down, and through to the other linked JIRA items. I’ve used quite a few organization-specific bug trackers as well.

Besides, you have to look for a software that can help you push data into the version controlling software. I’ve used Git Extensions to push data into Bitbucket, but I’ve found both SVN and VSS to be of equally good quality in their management and response. You can look at Git Hub, too.

For one of my previous stints, we’ve even used Microsoft Word for creating and managing the content. We would later export it to PDFs to circulate the technical documents to our customers. There isn’t one tool that I’d pinpoint as the best of all. But, based on the points I mentioned in the beginning, you can still zero in on what software you require for your organization.

I hope I’ve been able to answer your question.

Oh, and I published this answer on Quora with a disclaimer because I thought it would be nice for me to come clean.

What Writing a Book for Children Taught Me

Posted on by • Posted in Creative Writing, Spirituality, Technical Writing • Tagged , , , , , , , , , • 2 Comments

No, I am not breaking that I am writing a book for children; it is just another random thought that stuck me when I was researching on improving my writing skills. Turns out, one of the best ways I can improve my writing skills is to write books for children. I will write a book for children, but that’s far from even a start, as of now.

The big question of whether I will, one day, write and publish my own books still remains unanswered. But, I don’t want to confuse writing with publishing: they are two different things. And, for now, it is writing that I want to concentrate upon. This post comes at a time when I am learning to write. It’s been a while since I began writing frequently on this blog, and I believe the time has come to take things to the next level.

Now that I know that I can communicate my thoughts, and that the writing (Or is it typing?) flows as freely as my thoughts, I should try to bring all my energies, and the free-flowing thoughts, together to write better. Hey, I didn’t want to make this post look didactic… and I haven’t even begun yet. Never mind. There goes the rule number one: get thoughts and words to flow together.

When I began thinking on writing something for children, the immediate next question was: What should I write about? The thought of writing for kids was fine, but I was clueless about what I would write about. You see, there lies another rule. Even before you finalize on what you want to write about, and share with children, you have to be clear about how you’d write that. I mean your writing has to be so smooth that children (from age 3 to 10, roughly) will understand everything that they either listen to or read. Still, here are those rules that came in handy as I made a start:

  • Keep sentences short: Well, you are writing for those who’ve just stepped into the world of books. So, you better make it quick for them. The shorter, the simpler. The simpler, the better.
  • Use bigger typesetting: Use a bigger font size. And, preferably use the non-capped (sans serif) type font. For those who don’t know much about typesetting, the sans serif fonts are those fonts that do not contain the extra caps at the corners of alphabets. Such fonts are readable even when smaller in size, and largely appear informal, friendly in approach.
  • Don’t offer side notes: Unlike the way I did in the previous point, don’t use side notes and additional information that might break the flow. Remember, you are writing for someone with far lesser span of attention.
  • Let pictures do the talking: Use pictures that are colorful; that share an action or event from the story; that can help them imagine the rest of the characters. Seeing is believing; let them see the story for themselves. Avoid monochrome pictures, unless they are simple enough to understand.
  • Focus on grammar: You have to keep sentences short, but you don’t have to play with the rules of grammar. Grammar is like mortar; words are like bricks. If you use only loose bricks, the wall will not stand (or, stand for long). Also, stick to one tense across sentences, as much as possible.
  • Use imaginative relationships: See how I have been figurative in my comparison of grammar and words with mortar and bricks. Use comparisons that can help children build cross-referencing or poetic associations. Make them think; at least, for a while.

Those are some points about how I’d prepare either myself or my content. Now, some points regarding setting pages:

  • Cut short: Delete those sentences that do not contribute to the story or poem. This means, lesser content for me to bother about and for the children to read and understand.
  • One thought, one page: Make sure that the sentences don’t run into the subsequent pages. If so, break those sentences. That’s because, children might find it tough to reconcile their understanding of those sentences that involve more than one event described in sentences that run across pages. Children will most likely skip sentences if they have to turn pages back and forth to understand what’s going on. In fact, I’ve observed that most children hardly turn pages back and forth: they go along only one way.
  • Check for punctuation: Don’t use a lot of punctuation. Instead, let the pictures talk for you.
  • Leave with an afterthought; but not always.

Of all these rules, I’ve come to understand the following two as the most important:

  • Don’t lecture: No one wants to be taught. Learn to share.
  • Be a master weaver: If I can explain the story in just three sentences, I can expand it across the fabric and weave it into a story.

Then, there are other things like:

  • All black and white; no shades of grey (not the color, but the message)
  • Only happy endings
  • Don’t end with a question

But, it depends on who I or you ideally wish to address. Readership varies greatly within this age group. When I look back at the rules, I see that there’s a lot of similarity between what I do every day as a technical communicator and what I’d love to do as a children’s writer. Here’s the greatest of all catches: I understood, all the things that apply to the children’s books, apply to technical communication as well. I can’t exclude even one. I wish to come up with a book that will fancily be a part of every child’s bookshelf. Until then it is all black-and-white documentation (No, not the color, again).

Three Tips to Internationalize Content

Posted on by • Posted in Creative Writing, Technical Writing • Tagged , , , , , , , • 6 Comments

Last week, while I was talking to one of our teammates from the UK, this thought of writing for the international audiences drew my attention. I thought I should prepare a list of some generic points to consider while preparing content for international audiences. In this post, I share the that list with you. As a technical communicator, not often it is that I get to try my hands on localization (or internationalization, for that matter). Nevertheless, it is nice to know about the following points and put them to practice, whenever possible:

Culture-proof the references

This is by far the biggest cause of worry for the content writers. “He plays football” sounds a simple phrase to translate. But, as you know, more than one games share the spelling: The American football, the British football, and then there’s the Australian football. The English people wear black for formal parties and weddings. In contrast, it is not supposed to be good to wear black for weddings in India. As a communicator, if I come across any information that has a reference to a culture, I will like to either supply additional information or simply remove the reference.

I also make sure that I do not use any idioms, phrases, or initialisms that are specific to a location, culture, or race. For example: The Indians could have lost that match, had the other team not done a Devon Loch at the last minute. When you use idioms – like the one I used – you (or your translators) have to invest a lot of time searching for its equivalent counterpart in the language they are translating.

For those who don’t know, Devon Loch was a racehorse (Yes, racehorse is one word!) that collapsed just short of the winning line of one of the national horse races in the UK. That was in 1956, I suppose. So, you can use the idiom, only if you have the time and willingness to share the unnecessary background with the readers – assuming that your translator remains to be sane to translate it in multiple languages for you, multiple number of times.

Just for the fun of it, imagine translating the funnier idioms in the following sentences:

  • Today’s politicians are all talk and no trousers. (No imaginations, please!)
  • I’ve been a developer for donkey’s years. (Yes, trouble for you!)
  • Honesty will prevail in this world when pigs fly. (Seriously!)

There are also times when you generally refer to things from your own culture and expect others to know about it – unless you tell them about it. I’ve celebrated Ganesh Chaturthi ever since I was a child. But, to hear that this is a festival to celebrate the birth of the elephant-headed god was still weird for me. Still, the additional information helped my colleague explain our UK counterparts on what the festival was about.

Mind the Formatting

Formatting is one of the key aspects when it comes to comprehension. Translation can cost you the information if the formatting isn’t proper. During my stint as a freelancer, I’ve worked with a lot of clients who required translations from the English to the Hindi or Marathi language. And, in either of the cases, I faced issues especially with the alphabetical lists. Items marked until A, B, C, D, E, and F were fine, but anything beyond that became a little weird to read in Hindi and Marathi.

But, the comprehension is affected even when the language remains the same. For one of my clients, who, being from the US, used the MM-DD-YYYY date format, I had to get detailed clarifications for their date-based stamps that included one-digit dates. For example, 1-11-2016 is 11-JAN-2016 in the US, but 1-NOV-2016 in the UK. Not only is the date translation incorrect, but the difference is much as 10 months.

In some Indian languages, the bulleted list doesn’t exist in their legalese. So, whenever I’d receive scripts for translation, I’d double check for possibilities on using the numbered and unnumbered lists in their respective translated sections. It was time consuming, but definitely worth the time and effort. Speaking of the languages, some countries read right to left, like the Arabic or Urdu, or top to bottom, like the Mandarin. Are there any points that you consider when you localize, or if I may say, internationalize your content? I’d think considering placing screenshots in the middle of a page and using icons that aren’t specific to a gender, race, or ethnicity. But, I’m curious to know your opinion on it.

Error-proof your Data

The differences in the units of measurement are known to be fairly common ones. A 5’ is both five inches and five feet. In fact, this is so confusing that in some cases I’ve seen even 5” (a double quotation mark instead of a single quotation mark). Depending on the context of furniture designing, real estate, and even food – pizzas and cakes are measured in inches – the unit of measure will change. But, it isn’t as easy as it sounds. The standard unit of measurement for length in the US are Yard and Mile, while in the UK are Meters and Kilometers.

Then there’s also about the data integrity. If for a UK reader, I give data references like “the barren land is as big as the Lake of Utah, in the Utah state (UT, US)”, the reader will most likely either not understand it or completely misunderstand the estimate. Also, notice how states appear in the addresses in the US, such as the one we discussed. I cannot use the contracted form when I write the same information for the Indian audiences. For us in India, for example, the contractions UT and TN will never stand for the US states of Utah and Tennessee, but for the Indian state of Uttaranchal and Tamil Nadu.

Conclusion

I am a technical communicator, so I will only seldom get to try hands on localization and internationalization. But, in the limited amount of time and scope, I will find this list handy. Do you too have such a list? If yes, what are the points on your handy list?

Piecemeal Editing in the Agile Environment

Posted on by • Posted in Creative Writing, Technical Writing • Tagged , , , ,

Last week, I had a detailed conversation with one of my regular readers. While chatting over a few miscellaneous items, we drifted into talking about technical writing in the Agile-based environment. That is when he asked the following question. My answer led the discussion to more questions. This post is about those questions and answers:

In a lot of companies, which either follow the Agile methodology or claim to have sprints that are designed inspired from the Agile methodology, the technical communicators don’t have enough time for reviews and edits. How do you address challenges that arise in such situations?

I answered: As a technical communicator, I do a lot of things that majorly fall under either writing or editing. In a lot of my previous professional stints where we worked in an Agile-based environment, we could not afford exhaustive edit iteration cycles. So, we ran short edit cycles; mostly, quick checklist-based scans. For the most part, as writers and editors, we implemented our own versions of piecemeal editing.

Hey, what is piecemeal editing?

When pressed for the documentation delivery deadlines, writers and editors observe increasingly shorter cycles of creating, finalizing, publishing, and republishing the technical content. In fact, mostly they only get to republish the technical content, and not create any.

I’d call piecemeal editing as considering working and finalizing on parts of technical content rather than focusing on the whole project. It is a conditional response – an ad hoc arrangement, or sort of, at least – which is subject to the change in the prevailing situations. When you are pressed for time, you tend to focus on what’s:

  • Urgent
  • Important
  • Not worth missing

So, piecemeal editing is focusing on producing “just good enough” parts of documents that can qualify as a document when put together. The documents may still not be complete, yet will certainly contain everything the customers need to get things done.

How does it benefit?

Piecemeal editing is breaking the documentation plan down by focusing on making the instructions in your documents workable. You don’t cover the details, but still get to list everything that matters. You also don’t get to fix bugs, but still create error-free documentation. So, you save a lot of time and effort by concentrating on what needs your attention. This makes the writing clearer and to the point.

Are there any challenges?

Yes; much like every other thing. In the Agile development environment, the technical reviews and technical edits aren’t exhaustive. The editors do not have a lot of time to repetitively (Or, at least more than once) run through the writing process/the written stuff. So, all they get to do is keep a check to not miss out on anything critical.

If, for example, your organization assumes implementing the Agile software development methodology, you will continue to run in similar shorter sprints. This means you won’t get time to look into your legacy documentation or be able to edit and improve the quality of the technical content.

Then there’s another big issue: Unification. Piecemeal editing is One Thing at a Time, and not the whole thing at a time. Because of this, the contextual information that derives cues from the unification of information fragments often gets missed.

However, the biggest threat lies not in the process, but in the way it is often perceived implemented. When rushed, most writers become blind toward their mistakes. They overlook the errors by mentally placing words and associating meanings that the actual documents often don’t reflect. In absence of sufficient time, writers release the unedited versions of their content.

How do you resolve such issues? Or, are there any workarounds?

Technical documentation is always a collaborative effort – even if you are the only technical communicator in your organization. Here’s what I’ve tried and have succeeded at achieving:

  • When I worked as the lone writer, I would share the documents with the development/testing stakeholders. They designed and tested the product. So, they knew its limits. Also, when there weren’t any developers or testers around, I would perform edits the next morning, read those documents aloud, or just review the write-ups on a projector. Believe me, the text looks entirely different when you read it on a projector.
  • When I worked in teams, we would perform peer reviews. We would cross check the write-ups to make sure that we didn’t miss out on anything critical. Although, the writers would still remain primarily responsible for the quality of their documents.

But, here is, I believe, the BIGGEST condition: You cannot have piecemeal writing, but you can have piecemeal editing. It is “one thing at a time” as far as only editing is concerned. Writing will still focus on quality. Writing will still require commitment: The commitment toward creating and communicating correct information; in parts and in the totality. What’s your take at that?