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.

The Interview and the Strange Feedback

Last month, I attended a formal interaction for a job opportunity within my team. One of my teammates is looking for an instructional designer. Since it is a small team, they included us to review the candidate. That’s how and why the interaction happened last month.


In India — specifically in all the interviews that I have attended either as interviewee or interviewer — there are a few things that have gone unnoticed, unsaid, or but understood:

  • The interviewer asks more questions than the interviewee
  • The interview process has to cover all questions relating to the candidate’s professional life, including if and why was there a gap in their career
  • The interviewer has to have an upper hand or can interrupt


Thankfully, I have never followed any of these rules… and thankfully, organizations are evolving. Come 2021, I have rarely heard anyone facing such questions.


I am of a firm belief that first, it is an interaction and not an “interview,” and two it has to be two-way communication.

But, the recent interaction went from an interaction into an interrogation. And I am speechless.

So, here is how it went.


My first impression was that even though the candidate had over 20 years of experience, she didn’t have the positivity I was expecting her to have. So, I motivated her to talk more or elaborate right from her first answer. It might be true, after all, that the interview is over in the first 50 seconds.


Then, I asked her a few questions, which she answered promptly. And answered a few of her questions. Hopefully, I answered those questions satisfactorily.


Then I happened to ask her about the Oxford comma. I expect that a technical communicator with over 20 years of experience will have, at least, heard about it. She didn’t know what it was. To which I told her that I would have expected someone of her experience to know such things. Nevertheless, she appreciated me for pointing that out, and we moved on.


Then I picked up a few sentences from her resume and asked her to find out if and what was wrong with those. I was prepared to hear her say that the sentences were OK, which they weren’t. To which I would have said nothing.


But when she could not point out the oversight, I pointed out those to her and told her that she could correct those. Even though I realize this is an interview, I thought this helping hand would be acknowledged as a welcome gesture. Besides, I even clarified that the answers to those questions would not impact the interview result.


On a side note, let me tell you a secret. For all the interviews I have attended, I have purposely asked for the interviewers to point out the instances where I could have gone wrong or improved myself. I have always received welcoming replies. In the process, I have made friends with the interviewers… Selection or no selection, we have gone above and beyond those social boundaries to create a collaborative environment. I still talk to a lot of them, more as friends.


So, back to this interaction. I told the candidate how I committed mistakes and overcame those by asking the right questions. I also told her how I liked the interaction to be two-way, and not one-way. Within a week after the interaction, I heard from my boss — during our weekly interaction — that she found me to be aggressively authoritative and egotistic. Although we did clear the confusion between us (my boss and I), and even he felt nothing wrong with my approach, I have since learned a few hard lessons the hard way.


At least I now know one more thing. It is OK for me, as an interviewee, to ask what mistakes I committed. But, as an interviewer, I must not point out the scope for improvement, despite how objective and positive my intentions maybe because not everyone shares my state of mind.


Let me know what you think.

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.

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

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.

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.