Tag: TechComm

The Interplay of Information Architecture and Fictional Storytelling

As humans, we’ve been telling stories for a very long time. We’ve grown ourselves out of the various phases of human evolution because of the untapped contribution of stories in our lives. In this article, we discuss the interplay of stories and information architecture.

Insights from information architecture

Information architecture is the structure in which we produce information for consumption. It means that I must invest myself in understanding how I, as a content designer, can understand something before I help my readers put it to use. I understand this by using an analogy of online maps, for example. To reach anywhere, you input the destination, choose your mode of transport, and supply other conditions. Your route is your information architecture. Your choice of vehicle is your persona. Each persona has its set of conditions, speed of learning, and a preferred alternative (more than one route, in the case of online maps).

Let us look at what insights we can glean from information architecture and if we can apply those insights in fictional storytelling.

On perspectives

The following words are from a poem I wrote in 2021:
“Just as you have companions, my friend,
I have stories to keep me company.
The cat has only nine lives, remember?
As a writer, I realize, I’ve rather one too many.”
 

Sometimes, I am the user; sometimes, I am the project manager; sometimes, someone from the third party or vendors; I am everyone. I can assume any voice depending on the information I want to convey. I can adopt the indicative, imperative, or subjunctive mood. I can use the third-person perspective, much like Dr Watson’s voice that plays Sherlock Holmes’ mysteries in the reported speech. Or I can refer to the reader by a generic pronoun called “you”. I can sound encouraging through my words, such as “We recommend using this method for configuration”. Sometimes, I can sound cautious and be didactic, “Wear protective glasses when operating this machine”. I can also be someone who tells how the information must be accessed. Or I can be someone who tags the information for translation and use.

Each perspective has its way with words and will appeal to a specific set of readers, accordingly. I will explain things differently if you are an administrator and not a business user. As a technical writer, I can assume any role and adopt any voice to get my point across. We’ve discussed how we can make more believable characters and how we can use world-building to create contextually meaningful messages. The same thing can be applied using information architecture to create categories of contextually driven content.

On feedback

The reason feedback is often called a gift is because it lends you invaluable insights into the seeker’s brain. If a user story helps you step into the seeker’s shoes, feedback lends you an insight into their reactions and responses. Did the feature deliver what the users need? Did the users find what they were looking for? Did the users configure it correctly? Did the users accomplish what they had set out to? Will the users remember where to find the feature and its information again? Numerous such questions help draw invaluable insights. However, gathering feedback can be difficult. Therefore, to implement documentation and gather feedback, some organizations have begun using chatbots. Soon, we might use technologies like chatbots, artificial intelligence (AI), and machine learning (ML) to drive company-specific generative content, to help improve the findability of information. This translates to fewer support tickets and improved results from our cost-to-benefit equations: a better bottom line. All successful fiction authors follow the same or similar breadcrumbs from their readers. They are keen to glean such insights and implement them into their works. And much like fiction authors, we use the user’s footprints to lead us to the right design.

On clarity of thought

Of the many things that mire out my editor’s brain is the absolute thoughtlessness and absence of clarity that sometimes drips through a writer’s work. I infer, “If that’s how they write, that’s how they must think.” But sometimes, it is not the writer’s fault. It is the fault of the premise with which they begin to think. It turns out there is an order in which we must fix such issues. Begin, that is, with defining the customer’s expectations. We often get into this habit of describing our products’ features. But is not useless to tell what the product does? I can vouch that users are not bothered about the features. All they want is the underlying benefit.

In the context of fictional storytelling, this is much like the cliché, “show, don’t tell”. We must begin with the feature, yes, but we must end with the benefit. Perhaps, this is why, in the context of technical writing and information architecture, we focus on the underlying benefits. As a rule of thumb, ensure that your content doesn’t tell what the product does but what the users can do with it.

On techniques

Amongst the few techniques that help me write better are:

* Progressive disclosure: This involves spreading the message such that it unwraps itself over time. It unravels itself before dear readers such that its learning curve remains relatively flat. I prefer to use this structure when I am creating conceptual content. I lead the users to explore the concept before they delve deeper into the content. Consider this as an inverted pyramid where the tip of the pyramid­—which, in this case, is toward the bottom—denotes the most important message. The focus is on comprehension. In fictional storytelling, we use progressive disclosure for world-building and suspense revelation.

* Pyramid approach: This is easily the most used method in technical communication. I reserve it for all referential content and tasks. I share the most important information before I share the remaining content. This means the content is more usable. In fictional storytelling, we use the pyramid approach when describing an important event or narrating anything that involves a lot of action and drama. It helps create gripping content.

On copyediting

Seldom do we come across a better job than one that pays us to find other’s faults. I kind of love and hate it at the same time: On one hand, I speak of it in delight, but on the other, I abhor the idea of finding faults. However, I do like the idea of making things better. Besides, the task of editing makes me a better thinker. As the copyeditor for my team, I cannot afford to be slippery in my approach, thoughts, and words. At the same time, as a content designer, I cannot undermine the benefits of my copyeditor’s vision. The same skilled artistry that (sometimes) irritates my teammates also empowers my users. I cannot fathom not applying it in fictional storytelling, either.

Speaking of which, let us look at the insights that we can glean from fictional storytelling.

Insights from Fictional Storytelling

Fiction is imaginary literature that is written in the form of prose. It can be short stories, full-length novels, and epics that create a series of novels surrounding the life of your fictional characters. Fiction writing and storytelling both are about the art of writing stories. The difference is that writing is an art and storytelling is a skill.

Let us look at what fictional storytelling teaches us about our profession woven around writing, and if we can apply the insights in information architecture.

On characters

I cannot deny the power that our everyday conflicts have lent to our mental decision-making system. Conflicts trigger response, which triggers action; that passive sense of purpose (of resolving the conflict) is reassuring to us. It is even more useful if we can summarise our conflict in a single sentence. From start to finish, we can take our readers on a journey where they move from a mere thought to a compelling urge. We can drive their imagination to wherever our words take them—with them following us compulsively and unconditionally.

I also like to couple a character’s conflicts with their character sketches and motives. In all kinds of writing, those writers who do not characterize motives tend to lose their readers. Only when your characters can passively show why they are the way they are, your readers will understand why the characters feel or do things a certain way. Bear in mind that the readers don’t have to agree with the characters but must only understand them.


In the context of technical writing, personas are often detailed descriptions of who our users are and how they behave in a certain way. We use these personas to create content that matches the users’ requirements. Such writing has a twofold advantage. One, persona-based documentation is findable. Two, it passively empowers the readers by lending them the power to choose whether they agree with the persona. They understand the persona’s perspective and find common threads.

On choices

Writing fiction is difficult. It is a daunting task to find your way through emotions to seek the right description that matches the little bracket of word choices you and your readers are blessed with. To make the readers bleed through their eyes, you must first bleed your way through words.

You must consciously choose to rewrite repeatedly until you get to those core words that move your readers. Brevity in describing emotions is the key to this transaction. A character’s pain, for example, might make us feel that our pain is a lot lesser. In this way, writing is compassion woven into words. But this has a flip side. There is another type of people who find others’ lives as joyously painful and theirs to be painfully joyous. In another way, writing is decisive; it makes you take a stand. It must.

While I agree that there is no place for compassion in technical writing, I see the sense in which it is applied. All troubleshooting information and, sometimes, error messages are written in the same format: what happened, why it happened, and how to fix it.

On observation

We all uniquely understand reality. Each of us has a design, a pattern in which we comprehend this world. The fictionist within me is enamored by the enormous amount of detail that goes into this kind of world-building. I am fascinated by the works of writers like Charles Dickens whose novels are decorated with characters that speak who they are. For such writers, Babu from Mumbai doesn’t sound like John from England.

I want to make my characters believable, otherwise, how might you—my dear readers—will become the invisible observers of the characters’ lives? How will you believe that you are witnessing everything in real-time?

World-building does not apply to technical writing. At least not directly. But we do create documents that contain information built around the insights from world-building. We have different product and installation specifications for on-premises versus Software as a Service (SaaS) products. We have prerequisites for installation and requirements that might help our users in creating and deploying a virtual environment for testing. The more accurately we can describe the details of the environment, the more accurate the user experience is.

Conclusion

The art of information architecture is primarily restricted to setting the design right. What it lacks is often supplied by the insights gleaned from imagination. This is where the faculties of fiction and information architecture meet.

On conflicts and resolutions

To create a brilliant design, you must pare usability down to its simplest form. And, unless you understand the user’s point of view, it is difficult to know what matters to them the most. I am always curious to know what my application’s users think and want. I break those insights down into ‘manageable chunks of workload’. The input of workload contains cues to help me quantify output.

When I say, ‘manageable chunks of workload’, observe this hierarchy: User stories are divided into user scenarios, and user scenarios are divided into use cases. Each use case, therefore, has specific steps to reproduce, assess, improve, implement, and measure—in the same order. Much like with fictional storytelling, each use case, user scenario, or user story has a unique design in which the user comprehends, refers to, searches for, and builds their understanding.

On skilled storytelling

A world of masterful storytelling involves the elements of good content and good intent. It is not just how you do things, but also why you do them that impacts the people around you. Good content is “what and how” (underpinned by information architecture), whereas good intent is “why” (underpinned by fictional storytelling).

People often say that you eat first with your eyes and then your mouth. Likewise, you first listen to a story with your ears and then your heart. If the structure isn’t right, it might never reach your heart. A good design is like a delightful recipe that not only tastes good but also looks mouth-watering.

On wording

The art of writing is in meeting shifting targets. We all learn as uniquely as we explore. Yet, when it comes to reading, we all move in one direction: From the logical start to the logical finish. Yes, we sometimes skip the timeline to introduce or understand topics of interest. However, it all still points in only one direction. This “shifting target” of moving from the figurative Point A to Point B is immensely fulfilling for the human mind. It lends a sense of satisfaction. In one sense, writing is so much like life itself. We all learn life lessons before we glean the benefits. Likewise, while reading, we learn from wise words before the story fructifies.

Such is this mix-and-match of information architecture and fictional storytelling that leads us to invaluable insights into both fictional and functional worlds.

Wayfinding through Everyday Challenges at Work

“Do working hours drive you crazy too?
Often there is a lot of work to finish or even in normal days there are late eve meetings or some deadline to meet. Have you faced such a situation? If yes, what are such situations and how do you manage the work-life balance?”

Someone posted the questions on a regional WhatsApp group. I can hardly be blind to the question. And since there is so much to say, I thought of sharing it in a post here.

Yes, the prolonged work hours have now begun to show their effect, especially because I have not had the opportunity or window to go on a vacation. It has been some years since I took a leave for a few days at a stretch—and have purposely been away from work. Within this time, I’ve noticed that my capacity and productivity have gone up. However, my boiling point has considerably lowered. This means I get more angry more easily and more frequently. Even the fact that someone put up this question annoyed the hell out of me. 😀

However, with an emphasis on the word “However”, I have also noticed a few unexpected changes in me. I have become more patient with myself. I take time to understand things and I excuse myself for it. I feel tired, drained out, fatigued by the end of the day and I can barely crawl to my bed, but my quality of sleep has tremendously increased because I know that all I have to recharge myself are those five hours. I have entered into my automatic zone where I can barely feel myself doing my work-related tasks, it just comes naturally. In fact, if anything, I feel bothered and uneasy if I do not face any challenges on a given day. Each passing day reminds me of the “Hamdard’s Chinkara” advertisements that were aired when we all were young. Challenges or not, I feel I must pay either way; either with my callousness and lack of experience or with my dexterity and lack of time.

A lot of it depends on how you approach your work. AND a lot of it depends on how dependable your manager thinks you are. If they believe in “leading by example”, they can give you the authority, responsibility, and ownership of your products. It is an unsaid agreement that has mutual benefits and mutually dependent conditions. If I were an individual contributor, I’d choose to step up to match my role, expectations, and work. I’d clearly communicate how my doing my work impacts MY performance and MY life. But, if I were the team lead/manager, I’d communicate how my sharing the ownership and flexibility will help the TEAM grow. I’d share how little contributions from the team contribute to making a huge impact.

I’ve observed that unforeseen challenges, scope creep, new tools and methodologies, and more products/projects/features, all make me a better “me” every day. I am increasingly becoming efficient at compartmentalizing my thoughts and tasks, accordingly. Sometimes, I can foresee and plan for challenges and work items based on the product roadmap. Sometimes, I can accommodate last-minute challenges. Much like everyone else, I am guilty of letting my work creep into my personal schedule on a few occasions. But I can be flexible with how I approach my work. I can log off for some time for lunch. I do not have to worry about my login and logout timings. I can step out of meetings. And I can catch up with my work on Saturdays if required.

As for the work-life balance:
Set aside some time in the work schedule for:

  • Create (and stick to) a work schedule. Have definite login and logout times.
  • Ensure that you’re consistent and predictable in your work and work schedule.
  • Keep Fridays for only yourselves. Clear backlogs. Listen to recordings. Learn and share. Speaking of learning…
  • Learn something every day.
  • Listen to stakeholders. Tell them what you need. Help them with their last-minute tasks. Even a tiny help goes a long way. Remember, language is your forte and their challenge. Capitalize on it.
  • Make a list of work items for each day, each week, and each upcoming week.
  • Sort things/resources for you to use them the next day/week.

The key is to learn to communicate. Everyone feels burnout. We must voice our opinions when we feel fatigued. We must learn to say No. We must learn to listen to and consider the other side of the story. We must learn to look at the bigger picture. We must learn to listen to our hearts and follow our judgment. It is as simple as that; it is as difficult as that. Still, there always is something unaccounted for, unforeseen, or unplanned. But then, isn’t life more about the moments that take our breath away than about the ones that don’t?

I’d be curious to know your opinion. Please feel free to add to the Comments section.

Documentation Insights: My Derivation of a Design Thinking Technique

While I can never understate the importance of documentation standards, its inspiration or source is often overlooked. Today, organizations have their own sets of guidelines. So, when my manager asked me to create a set of guidelines for my team, I took to it with the utmost consideration. I realized later that the care I bestowed upon creating the standards itself underpins the very core of our everyday tasks. Thus began this little journey of experimentations and revelations.

The Problem(s) at Hand

Creating or having documentation standards isn’t the challenge; ensuring their adherence and relevance is. So, yes, we had a relatively bigger problem at hand. However, the real problems lay much deeper into the layers of our existing processes, legacy documentation, and upcoming challenges. First, we had multiple sources of truth. That is, if it was even the truth — or if it was still relevant. And, second, none of us knew how we could align our tasks with the other teams. Our team was to document the stuff just as it was ready to be pushed out of the door. So, documentation was to be found on the priority list only AFTER the other things were ready.

I am a LUMA Practitioner. It is a design-thinking approach that lends you 36 insightful human-centered design methods. My first introduction to the technique happened briefly during one of our quarterly meetups. As our instructor lead us through his story, I realized how even in this case, the problems weren’t the ones at hand but the ones buried within the layers of their processes, tools, and challenges. Back then, he and his team followed British Design Council’s Double-Diamond — another human-centered design approach. Even though this method wasn’t a part of LUMA, I could immediately see its effectiveness in helping me resolve the problem(s) I had at hand.

The Technique and the Insights

For those who might not know, Double Diamond is primarily a team-driven activity that breaks down the thought process in waves of divergence and convergence. Each of the four stages, viz., Discover, Define, Develop, and Deliver, follows a pattern where the team members are required to either diverge or converge their thoughts. The idea is to discover the root of the problems and then brainstorm to derive a solution. Discovering the core issue, therefore, requires your team to diverge. But, Defining, which is the second step, requires your team to converge their thoughts and come up with the definition of just one of those core issues.

Those who want to read more about British Design Council’s Double Diamond, click here:

https://www.designcouncil.org.uk/news-opinion/what-framework-innovation-design-councils-evolved-double-diamond

As I skimmed the Internet and continued to refine my ideas, a few things became clearer:

  • I was already past the Discover stage.
  • I, on my own, could continue to refine my ideas using this technique, even though it is a team-based activity.

I assumed that my understanding was at par — until that mental checkpoint, at least. So, now I had the right approach, intentions, and need.

The Derivation

To further align my thoughts with this approach, I revamped Double Diamond to create a version of my own. The new four stages, for me, were: Define, Design, Develop, Deliver. I categorized the first two and last two in pairs. And for each of the pairs, I came up with role-specific guidelines for both writers and editors. But before I talk about the actual guidelines, I’d want you to remember that the guidelines are specific to my team and might not necessarily apply in your case.

In the ‘Define and Design’ phase, I recommended that writers come up with the following questions for clarity:

  • What is your business proposition? Or, what problem do you solve with this product offering, tool, or solution?
  • Do you have time constraints? Or is this a project with a shifting deadline (an ongoing project), something that you might build on the go?
  • Where will we keep the content?
  • Who will remain the owner of the content?

For the same phase, the editors would ask questions like:

  • How is the product placed in the overall ecosystem? How does it interact with the other tools? Or, typically, how does the data travel from Point A to Point B?
  • How much ownership does the writing team have?
  • Who else is involved in the content finalization process?

In the ‘Development and Delivery’ phase, I recommended that writers lay stress on the relevance of content. To help writers build their understanding of the term ‘relevance,’ I broke it further into four points, each of which adds significantly to the content:

  • Critical relevance: The content should help readers survive through, or triumph over, the uncertainty, lack of information, or misinformation.
  • Contextual relevance: The content should be what the reader was looking for when they chose (yes, looking for information must be their conscious decision) to get to your content.
  • Emotional relevance: The content should help readers make decisions on their own, rather than we deciding on their behalf (unless we are recommending something).
  • Strategic relevance: The content should help them see the previous and the next steps. Or, it should help them see how what they are working on fits within the bigger picture.

For the same phase, the editors had to do relatively smaller yet more critical work. They were required to preserve originality.

The Conclusion

My version of the documentation standards is a five-pager Wiki that highlights time-critical information in a time-efficient way. It may not be perfect. Still, it does what it is supposed to do. Did we become better writers? No. But we most certainly became better readers (of the user’s thoughts, that is). We developed an empathy for the readers. We now understand their pain in a much better way. None of the stages diverge or converge, yet the phases make you think. And that’s enough for a better start. So long as we ask meaningful questions, we can hope to derive equally meaningful answers and insights.

The derived version of the Double Diamond approach aligns better with what I had on my mind. Three months down the line, I see that we can take care of a lot more work than we used to. In addition to ensuring consistency and reducing the efforts in edit iterations — which were some of the primary objectives — improving work efficiency turns out to be a bonus. I’d be curious to know if there is any such approach that you found helpful. Or if you, too, have a derivation for your reference?

My Article in CIDM Matters (October edition)

In the October edition of CIDM Matters, I talk about the top 3 things to consider when writing for internal customers or subject-matter experts. Here’s is the link to my article that recently got published in CIDM Matters, which is the electronic newsletter of the Center for Information Development Management. To know more about CIDM, click here.

My Article in STC India Chapter Indus (September edition)

In the September edition of Indus, I talk about how I broke into the field of technical communication. Here’s is the link to my article that recently got published in Indus, which is the electronic newsletter/magazine of the India Chapter of the Society for Technical Communication (STC). To know more about STC India, click here.

My Article in Writing & Beyond (September edition)

In the September edition of the Writing & Beyond, I talk about the top 3 skills for a technical writer. Here’s is the link to my article that recently got published in Writing & Beyond, which is the electronic newsletter of the Tech Writer’s Tribe. To know more, click here.

My Article in CIDM Matters (December edition)

In the December edition of CIDM Matters, I talk about empowering the seeker. Here’s is the link to my article that recently got published in Matters, which is the electronic newsletter of the Center for Information Development Management. To know more, click here.

Three Tips to Internationalize Content

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

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?

Why Isn’t a “Help” Helpful Enough?

It is strange – and true – that technical communicators, like you and I, are into a profession that most others care a damn about… unless, of course, they are in dire need. No wonder most of the users yearn for the documentation only for troubleshooting their stuff. “I want to somehow get through this”, they intend. So, for the most part of their exploring the product, the users are busy finding answers to their how-does-this-damned-thing-works questions. Why is it still that we are unable to design formats that can make the users’ troubleshooting pursuits easy and manageable?

If I think about this whole thing as a user, it seems a daunting task for me to search for something I am not sure about; All I want is to solve my problem. But, how do I go about the help? How do I know where exactly to look for? How do I make sure to turn all the stones before I take a step further? How do I know how much information is sufficient? How, just how?

The users, I find as a technical communicator, use the following justifications for sending verbal curses to our so called “Help”:

  • Can I search for pictures? Does your help contain data/metadata to support searching for pictures?
  • I am lost. Where am I? What was I searching for? Is this what I was looking for?
  • I am tired. I’ll rather sleep.
  • I believe the reviews on the Internet provide more information than you can possibly cover in your next ten iterations. Sorry, I prefer the reviews.
  • I got the Internet; I will Google things up! I don’t need you.
  • I have other, better things to do.
  • I want a PDF. Do you take orders?
  • Is that a Help? Almighty, help me!
  • That many pages… are you kidding me!
  • The help only answers questions on information that is otherwise obvious and easy to locate and resolve. Why would I need answers to such simple things?
  • This help is outdated. Is there a new version?
  • This isn’t what I was looking for.
  • What I read partly solved my problem. What about the issues that remain? And, where can I find information about how to resolve those issues? Hello, are you listening?
  • Why aren’t there any graphics? Your writing sucks!
  • You call those graphics? I am better off with the written text.
  • You can’t expect me to read 20-odd pages just to look for a one-line information tidbit.
  • Your help does not contain the keywords that I am searching for. Why?

Sadly, this isn’t any one-person opinion. Most of them have equally creative, purposeful, and heartfelt verbal abuses for the help texts we share with them. Fact of the matter? The help isn’t helpful enough. Yes, it is true that a product is like a shrine with a thousand doors, and that the devotees can enter from anywhere. Yes, it is true that each devotee has a story to tell and a prayer that they want heard. And, Yes, it is true that it is close to impossible to predict the needs of each devotee. But, hey, isn’t that what we do every day as technical communicators? Just some food for thought.