Voice for Product Documentation: Alexa/Siri/Cortana/OK Google

This article is a summary of the author’s session at STC India Conference 2017 Design Voice Experiences.

By Ravi Kumar Adapa

Imagine a customer who is struggling to install a complex enterprise product ABC… simply says “Alexa, tell me the procedure for installing ABC”. Alexa reads the procedure out for the customer to complete the installation. Simple, no? But what is Alexa and how does it know the procedure? Alexa is the Amazon voice assistant. It is designed to take the trouble of navigating to the installation section of the respective product documentation and read out the procedural steps to get the job done.

Sounds like a scene from a sci-fi movie?!! Not at all.

Voice Assistant for Documentation

The voice-driven experiences are receiving great traction. See how technology giants are launching a voice assistant one after the other: Alexa, Siri, Cortana, and OK Google. This article highlights how the Technical Writing community revisits its content structure, makes necessary amendments to content architecture, and further enhances customer experience.


Why Voice?

According to the Trends Report, there will be over 200 billion voice search queries per month by 2020. The newer non-screen search devices such as Alexa, Google Home, Cortana, and Siri along with other advanced technologies make your life very easy to search anything using voice command. An instant answer or action improves the overall customer experience.

This technology is still in the nascent stage and it’s going to have teething issues, but remember that Voice is the future!

No AI without IA

Creating technical content that is voice-ready is the need of the hour. Just like how we use mouse, keyboard, and touchscreens (click/type/touch) to navigate to the pages for information; in future, you will be talking to devices for information and help. In short, the current user experience, which is mostly visual/textual, is gradually being supplemented with voice.


Conversational bots and interfaces do not automatically learn how to talk and behave. Humans need to teach them. When designing any natural language interaction, machine learning alone will give you exactly what you’d expect: robo-talk. You need to manually feed the responses to the possible questions through the anticipation.

Conversational UI is a reality and requires not only innovative engineering, but human-focused expertise in design and creative writing to achieve the nuances of effective, thoughtful, and personal conversations. That’s where the Technical Writing community strength lies!

Getting Started with Writing for Voice

At the core of AI, ML, and NLP lies the structured content. Any bot can only be as good as your content and its architecture are. As a technical communicator, you should redesign product content. Just like how we have DITA and information elements, we have certain recommendations for writing for voice.

Writing for chatbots and voice bots require a thorough understanding of the following basics.

You need to create micro-content for providing answers to customers’ in-context questions. The answers should help customers with their tasks through Intent, Utterance, Action, Slots, and Fulfillment.

Voice Technologies and Technical Writing

Technical writing has evolved with the changing dynamics of contents – writing for print, PDFs, GUI, Web, Mobile, and now voice interfaces. Be it smartphones, smart watches, car dashboards, or smart entertainment, voice-as-interface is emerging as a simple-to-use and hands-free alternative for content consumption. Voice also brings human-like interaction experience in finding the right content at the right time with the support of NLU and AI.

Voice Interfaces can:

  • Provide the right answers at the right time.
  • Optimize buyer and customer journey and overall experience.
  • Minimize support efforts and costs.
  • Ensure greater Time-to-Value (TTV) for customers.
  • Amplify digital adoption for products.
  • Increase the value of your enterprise investments.

Voice in Documentation: Use Cases

Technical Writers can use voice technology for almost all practical purposes such as installation, configuration, troubleshooting, and rich media content types. The possibilities are literally endless. See the following examples:

Onboarding Experience

When a customer gets started with the product, Alexa can help them with the installation and the getting started information. See the entire conversational flow between a user and Alexa:

You: Alexa, ask CA Digital.
Alexa: Hi! Welcome to CA Digital. I am your product experience partner. For a list of commands any time, you can say ‘ask CA Digital’.
You: Thanks!  I need help with one of the CA product.
Alexa: Sure, let me know which product you’d want to install.
You: CA Advanced Authentication
Alexa: Thanks! That is one of the most popular CA products. The latest version of this product is 9.0. Would you like to install?
You: Yes please.
Alexa: Great, let’s get started with the Pre-installation steps
You: Tell me about the first steps
Alexa: For AA 9.0, you need to have JAVA 1.8 and an Application Server installed before you start with the installation. The available application server options are Tomcat, WebLogic, J Boss, and WebSphere. Do you need any help to install them?
You: No, I will install them myself
Alexa: I am sending the version support details to your App. Let me know if you need 
any help.
Alexa sends a card.
You: No problem. I will do it.
Alexa: Let me know once you are done.
You: Alexa, I am done with the prerequisites.
…. Continue with the rest of the steps as guided by Alexa
Alexa: Review the installation summary details and click install to complete the 
You: Thank you Alexa, I have installed the product successfully.
Alexa: Oh, that’s wonderful to know. Wish you a great product experience.
You: Good! You have been a great help. I am sure the product would be as good as your help.
Alexa: Happy to help! Good-Bye.

Troubleshooting and Error Handling

When a customer gets an error, he can talk to Alexa for self-service. See the entire conversational flow between a user and Alexa.

You: Alexa, I am getting an error while authenticating Push Notification. Can you help me fix it?
Alexa: Sure, please read out the error code and the error message.
You: 401 for URL java input output exception:
Alexa: Thanks! This error is due to FCM server key. Ensure FCM.ServerKey is properly set in PushProvider.properties file at CA Adapter home.

In both the examples, we as technical writers play a vital role in designing the conversation flow. These PoCs can be expanded further.

What Next?

Is voice technology limited to product documentation only, nope! You can use this for your Sales, Marketing, Support, Sustenance, and all the possible touchpoints to get the most out of a product. In fact, voice technologies can be great products too. All in all, voice technologies can add great value to a successful experience for customers. Remember, Customer Experience is everything and THE PRIME DIFFERENTIATOR of a business, as rightly said by Otto Berkes, CTO, CA Technologies.

About the Author

Ravi Kumar Adapa, a regular speaker at STC India annual conferences, is a Senior Information Services Engineer at CA Technologies, Hyderabad. He carries with him 18 years of work experience that includes writing, training, customer experience, team management, and project management. He is an M.A., M.Phil., in English Language and Literature with PGCTE and PGDTE from CIEFL, Hyderabad. Besides writing and designing, he has a child-like curiosity and passion for new tools, apps, and technologies. He brings future-ready ideas and is an active contributor to technical writing community in India.

On the family front, he lives in a joint family and loves spending time with his two li’l daughters Tanmayee and Chaitra.

See his talks on YouTube: Decoding The Viral Quotient of Technical ContentTransformation from being a Cost Center to Profit Center


  1. Hey Ravi!
    Already heard your multiple sessions and all of us from Hyderabad were lucky to be see your hard work resulting into first of its kind in our Technical Writing conferences – introduction of speaker by Alexa.
    Kudos to you for your innovative approach.

  2. Hi Ravi,
    Your thoughts are very innovative. Be it a presentation on Alexa, and presentation in STC conference, ‘Content as a Cost Center to Profit Center’…You always try to introduce new technologies to the Tech Com group.
    Keep sharing your innovations in documentation.

Comments are closed.