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?

Advertisement

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.

Don’t Fix What Isn’t Broken!

We all learn. And, here’s the post on one such thing I learned, recently. For one of the projects I worked before I switched jobs last week, I was the only tech-comm contributor who held the dual role of preparing technical content as well as marketing collateral for the flagship product.

Until that time, I thought that technical writing made me be proud of one habit of pursuit: Perfection. I have grown, learned with time. And, I have gradually improved on my work and writing style. Consequently, I have developed this habit of looking for perfection in what I deliver, both in my work and in the blogs I publish.

The tasks required me to prepare the “usual” user and administration guides and then some customer-facing, enticing marketing collateral to increase the purchases of our products. I took up that dual role on the special requests from the content writing team lead, because I – being the sole writer for the thread – could explain the products’ core strengths.

Though there were a lot of things that I improved upon in the project, there were some that I had to leave untouched as I wrapped up. Friday was my last day at the office. I also had the other engagements at my home to look into before I joined my new company on Monday. So, I was hardly left with any energy and time to manage the tasks pending with me.

I knew – and still know – that had I tried harder, I could have managed a couple of additional edit iterations on the marketing collateral I prepared. I wanted to share only the perfect content with my then customers and colleagues, but I was short of time. Just one more write-up. One more edit iteration cycle; another better version. One more day. One more feature. One more document. One more inch toward perfection… just… one… more…

<Pause>

Please realize that I don’t WANT to commit mistakes – no one wants to. Also, I don’t think that I am perfect. But, knowing that fact does not – and cannot – stop me from TRYING to be perfect. And, here comes the wisdom: I AM WRONG.

Don’t try to fix what isn’t broken.

The truth is: One of the biggest challenges in technical communication is feedback. And, it is good to assume that even if the users provide feedback, it is only for what (they know or they think they know) is missing from your documentation. Assumptions are good. So, if they never get back to you, you can ASSUME that you are good to go. Like it or hate it, it has always been the way to go for technical communicators.

But, if that is true, then what is perfection?

Perfection is the state of being “all correct” in a situation, given a premise, under specific parameters, and at a certain point in time. Given that to be true – I can’t find a definition better than that – I think perfection is BAD. It stops you from progression. Progression toward a version better than you created. Perfection is status quo. And, I want to continue to flow. I want to continue to evolve.

Once upon a Time in Technical Writing

Stories are the commonest way the ethics, histories, information, insights, and knowledge have passed on to the younger generations. Through its multiple forms, storytelling focuses on building touch points to get messages across: Something that we too do as technical writers. I try to find the threads that storytelling shares with technical writing. And, here’s what I find as I try to delve.