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?

Advertisement

TechComm and Content Disruption

Vinish Garg recently posted on the content’s role in Disruption. In his post, he shared what the experts had to say on the role that content has to play/currently plays. Here’s my opinion:

What is Disruption?

Let me first take you back in time. This started when the marketing and branding industry opened the corporate gates to the world of consumers. And, by opening the gates, I mean it transformed its value proposition from “this is what I have” to “this is what I can do”.

This is when the small brands started becoming revolutionarily big by using the power of content to reach people. Gradually, the brand communication transformed from advertisements to jingles, to sports, to brand personification, and to emails. But, this inherent idea of associating brands with emotions continued to lose its value as the size of content continued to become unmanageably big.

Today, we have a lot more touch points to reach to our consumers, yet we are far less effective in reaching the right audiences. Reason? The consumers are lost in the enormity of content. In the race of creating more content, we have forgotten to make it effectively personal. Today, the consumers have a lot of options, and each of those options is trying to be different. But, when everyone tries to be different, no one is different.

It is important to disrupt this clichéd template of communication to help consumers make informed decisions. It is important to keep consumers at the focus to design communication strategies that transform the value proposition from “this is what I can do” to “this is what I can do for you”.

This disruption is to bring back the consumers from the point of “I am being pushed” (with the product/service) to “I am being heard”. And, only such a disruption can help us engage better, listen better, and do better.

And, how can technical communication/technical communicators play a role in Disruption?

I think it is about the consumers, and not about the product. We exist because the consumers (and their needs) exist. We help build this communication ecosystem. We communicate products in an undistorted, unappealing form. But, we do connect the features and benefits. We can help our consumers answer the “what’s in it for me” question. Of course, we may not sell. But we can at least help them buy.

I look at it this way: If organizations were chemical equations, technical communicators would be the catalyst. We communicate. And, we help communicate. The information passes through us. So, it is up to us to transform that information into its utterly simple, memorable, and usable form. In fact, we can equate customers’ requirements with the developers’ intentions.

We can align tools, methodologies, and the technology while we bring clarity, insights, oneness, and simplicity (not in that order though). But of course, that all sums up as the easy-sounding commonsensical task. And, making common sense truly common is perhaps the disruption.

Connect Those Pesky Dots

“For god sake, once, just once, connect those pesky dots. Can’t you see that I can’t understand anything? Even a word?” That’s what I often say when I look at bad write-ups. I just can’t connect those pesky dots to see what the story is. But, am I the only one who rubbishes write-ups that often? Don’t you too?

I think a write-up is bad because it doesn’t tell me anything. So, if it is poem, I am like “Uh!” and if it is a story, I’m like “So?” Write-ups that do not take either me or my learning from, for example, point A to point B are bad write-ups for me. I do not read poems. Not from all the writers. I am choosy, because not all writers do justice to their works. But, here’s one who I read quite often, and every time I see a new poem, I realize the poet wants me to step into her shoes and flow through the story she narrates.

But then there are those writers, who can beautify their words, and still fail to get the messages across. In contrast, I would love to read those writers who can break the ice, tell me a story, and make me smell the flowers as I read through their texts – just like the Juhi’s poems I just shared with you. Such writers, I believe, are a lot more effective. That’s because they have a message for me. Beautification is not a message. Beautification may be important, but not for me.

My take? Fiction, non-fiction, biographies, and poems: I see that the quality of write-ups (good or bad) depends on the flow of thoughts from the intentions to the messages. This flow is what can help us connect those pesky little dots. The message in the flow is about something that I either need to know or am interested to know about. And, as long as the writer can help usher me through the tides of the emotions, and still communicate the message and bring me (or my learning) from point A to point B, I’m good.

Plain, simple rules, aren’t they? Flow and message! But, why am I writing this to you? Why? Or, is it not something you already know? How many of us not write to rant out our pain? How many of us write for the fun and soul in writing? I am not sure. Not sure, because I know that writing isn’t always for a purpose. Not sure, because we know that we know the principles or the idea, and yet not follow it. Most of us don’t. But, I think I do. Do you?

The Next Big Thing: Workshop

Next month, I am conducting a couple of workshops at the STC India Annual Conference, in Pune. I like to talk about technical communication. And, at the conference, I’ll meet a lot of those would like to talk to me about this faculty of knowledge. Also, information design, as a topic, has always fascinated me. And, this time, I am conducting the workshops on the same topic.

In one of my recent interactions, with the Information Design batch at the National Institute of Design, we discussed some design principles. This is one of the reasons I chose to talk about information design at the annual conference. I see that a lot of new writers in our faculty of knowledge are turning toward information design. And, all this just makes me more curious about the topic.

I plan to keep the same flow of thoughts for both the workshops: I will make my point; then I will help you explore the topic; and then we all will draw conclusions on it. The first workshop is on the pre-conference day, and the second on 11 December. You can read more about the first and second workshop using the following links: Workshop#1 and Workshop#2.

The colleagues at my office too are excited about the workshops. In fact, some of them have asked me about how they too can attend the conference. In case you have not registered for the conference, do so quickly. Those of you who regularly follow me on the social network have asked me questions about the workshops. One such question is about a typical format of workshops. That is an interesting question. In fact, that’s how I began my research when I was invited to speak at the conference.

My research says that every workshop (and the speaker) is different. So, there cannot be a fixed format for workshops. However, I think there is one template that every speaker follows: First, make a point and describe it; second, create an exercise for the attendees; third, restate your point in light of the exercise to help your attendees connect the new insights with the thought you initially established; and in the end, leave your attendees with a thought.

But, there is one thing I would hate to do at my workshop: lecture about things. This is YOUR time as much as it is mine. To be a little too specific, you have two hours with me on the pre-conference day (that is 10 December), and 45 minutes on the day that follows (that is 11 December). Please remember that these are interactive workshops. So, the topics cannot steer ahead if YOU don’t participate.

At the workshops, I aim to talk about some intuitive design principles that can help map the need of the user with the benefits of your products/service. But, unlike what most of us think, these principles do not belong to information design. The principles are what I call the torchbearers, because they remain same no matter what faculty of knowledge I apply. This is enough now: I won’t spill the beans! Attend the workshops to know more.

Three Tips for Effective Localization

In this post, I take a closer look at the localization project in which my team and I assisted. I take cues from this project, and the similar ones that I have done previously, to discuss the top-three points for localization. This post is special to me, because it has helped me unfold those chapters of my life, which I had come to forget. If you are new to localization, this post will help you scratch its surface. If you already are into this field, I hope that the post will help add some new points to your localization plans. Click here to read the full post.

The Writing Principles

Have you ever come across a poorly written write-up? Have you ever felt that you could have written better? A couple of write-ups, which I read recently, drew my thoughts on writing about writing. I have always believed that anyone can write. But, if everyone can write, can everyone become a writer? I have explored this thought, and prepared a list (… which is not really an exhaustive one!) of guidelines that can help everyone write better. Read the full post.

Information Projection: Where Meet Information Architecture and Information Design

The new capability that we introduced into our flagship product helped me learn a lot about information architecture and information design. But, this post is about information projection. As I understand, it lies on the overlap of information architecture and information design. The post is also about the layers of information projection elements and the parameters that affect those layers. Click here to read the full post.

The Inverted Tree of Information

I will start this post where I ended the previous one: the inverted tree structure of information categorization. As promised, I will talk about my interpretations on some of the verses in the Bhagwad Gita, which is a great source of inspiration for me on both, personal as well as professional grounds. Click here to read the full post.

For Your Information

There are a lot of things that drive our searches. Therefore, it is true that we often search for things that we don’t know. Or that we begin searching for one thing and end up finding another. And, such information is not a goal, but a by-product. But wait; there is lot more to this story. Come, see for yourself.

The Ps that remained

The fact that I am a marketing graduate has had a considerable impact on the way I handle product documentation. I largely take things from the user’s perspective: Unlike the way a technical grad would handle documentation, I mostly like seeing it from the eyes of a marketer. While I was recently busy answering the “what’s-in-it-for-me” question (during the product documentation for an upcoming release), I stumbled upon this strange similarity between my education and my profession. Click here for the full post.