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

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

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.

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.

The Ad hoc Content Writer

This month has been really exciting for me at the office. That’s because, from the first day, I played only a technical communicator. But in this month, I added some more feathers to my tech-comm cap – Newsletter and Blogs!

I delivered a big project at the start of this month: Administration, installation, and user guides; a CHM help; and a couple of utility documents. And, all that as the only writer for the project. Another project on the professional timeline, so I thought. But, the company had other plans for me. As I waited for other projects to start, my company gave me this opportunity to take part in the first-of-its-kind project, the company newsletter.

We decided it to be on the online platform, and in only about a couple of weeks, came up with the first draft of the newsletter. It must have been our efforts (and some luck) that we got the draft approved WITHOUT A SINGLE CHANGE. The newsletter is now live, but because it’s for only internal circulation, I cannot share the link with you.

My manager knows that I have a blog and that I contribute a fair amount of time to it. So, he assigned me to work with the content-writing team lead, and come up with blog posts for the company’s online presence. The efforts are to be a part of the company’s India marketing campaign. And, I am excited about this new ad hoc role of a content writer. Of course, I am still pitching in with the usual technical-communication efforts, but putting in efforts into the marketing side of things seems more like re-reading some old pages from my past.

In the coming weeks (or days, perhaps) I’ll share some of the blog posts I wrote for the company’s online presence. I hope you will like reading them. For ease of reference, I will hashtag those posts as #AdHocCW. Do let me know how good I do as the ad hoc content writer. One last thought: It has not been difficult for me to play the roles of technical communicator and content writer. I have always thought that technical communicators can excellently double as content writers; just that now I can say that more confidently.

What questions do you ask to SMEs to begin with technical documentation?

During a recent online conversation, someone requested for a list of questions I would typically ask to a subject matter expert (SME) to prepare technical documentation for a topic. Of course, the parameters may vary, but there is still a list of questions that apply across all sizes or complexities of projects. In this post, I share with you the list of questions that I shared with them…

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.

Do you create video reviews on newer technologies, too?

Time and again I get to answer the question about what I do for a living. Yes, it does get irritating at times. But, mostly I love answering such questions. This time around, it was a marriage party and the questions were from the father of a curious teenager.

“So, I heard you are a writer!”

Is that a question? No, he knows that I am a writer. It’s just a rephrased form of “So, though I know that you write, I’m curious to know what [the hell] you do for a living?!” There still are traces of suspicion, amazement, and non-knowledge, which I liked. Tip: Never let the other person know that you know how it all starts.

I said I don’t just write. Just to be informative, we – in India – mentally associate writers as mostly boring, wage-less people who write because they cannot do anything better than that. So, I said, I don’t just write, I work as a technical writer.

I continued, “I prepare technical documentation for a software company. We, as a company, create software blah… blah… blah… and I get to create user manuals, troubleshooting guides, and the other *important* stuff, which is similar to the guides that you get when you purchase mobile phones.”

“Hmm… OK!” [Expected reply.] That’s a sign for you to continue. So, we talked for some more time before this happened…

“You see, my son keeps searching on YouTube… he mostly searches for [and watches] videos, spoofs, reviews, and funny stuff on technology… Do you do anything of that sort?”

Spoof? Well, No! Reviews? Still a No. Videos? Maybe! He probably intended to say “tutorial” for “spoof,” but alas there weren’t any translators available. Nevertheless. That’s another word to add to the list of what I DON’T do for a living.

Toward the end, I could give him a fair idea of what I do to earn a bread (and the other edible stuff). It turns out, he too wrote occasionally. No, not the way I do, but he wrote poems and diary entries. He wanted to start writing more intently and found “So, I heard you are a writer” to be the only way to crack a conversation about it. I totally respect that.

We kept talking for about half an hour; It was nice talking to him. Our streams of thoughts converged when he asked me about that “one *all-important* thing about my profession.” From where I can see, there is only one answer to this question: Curiosity.

Though we never really concluded the conversation, I got to know one thing toward the end: the curiosity of the curious teenager was very much visible in the eyes of the now curious father. He was content with my reply, it seemed. But, I think I saw a writer in the making.

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.