The Writer’s Responsibility

Let’s look at this scenario: Your product support team gets a call from an exasperated customer who could not upgrade their environment to the latest software version. They tried everything that the document instructed them to do. But upgrade didn’t happen or failed. Support cannot figure that our either. Engineering and QA representatives get on the support call and after a lot of digging, find out  that the user is doing it all wrong. They fix it. Then they ask the user “Why are you doing it, instead of this?” User responds, “Oh we followed the document.” Out of nowhere you receive an email with the subject line Documentation Error. You know full well you followed through with everyone for information. You send multiple review requests, updated multiple review feedback. Someone even provided feedback on this particular statement. You fixed it. And now, this documentation error. This is a genuine situation with a customer. What do you do?

Do you get angry, dig into your email to find the exact email that instructed you to write what caused the problem and start a blame game series and spend time fuming and anxious? If you say yes, I won’t be surprised, but will ask you this. Is your anger and being upset helping you to fix the issue and resolve the problem now? Or makes you waste your time and others time by turning this into an unproductive negative situation? Why do you get angry? Is this your personal book that someone is finding fault with? No. This is a document with a purpose. If the purpose id defeated, then it doesn’t matter where the fault is, documentation is part of the product and it is our responsibility to fix the issue immediately.

As technical writers, we are responsible for the Integrity of information. How do we maintain the integrity of information in a technical document?

To maintain the integrity of information, you need to make sure you develop the right information, get it reviewed and by updating the feedback. You also have to constantly monitoring the product during development, touch bases with dev and QA folks to see if any changes are made in a particular feature after you have documented that feature.

• Information Development:  We may be working on a release notes, installation guide, user manual or context sensitive online help. Make sure what we write aligns exactly with what it is supposed to do. Read your FS, talk to you developers, talk to you QA, use the product (if it is SW, or if it is HW and you cannot use it, walk over to the lab and watch the QA or lab technician use it) and write the content.

•  Review: After you write your first draft, follow-up and follow-through with your SMEs for reviews. Make sure they read your document and provide feedback on your content. And make sure you update your draft based on their feedback. If you are in agile environment, your initial draft will have to change a few times before the product is shipped. So make sure to periodically revisit your draft and get it reviewed and updated. For installation and upgrade related information, write, get it reviewed and find someone on your team who had not done the installation part. Ask them to use this document and install the product. Understand what issues they go through and fix it in the document.

• More review: When the document is almost close to the final stage, get in touch with you PM or TME. Request time with them to go over the document or a feature content.

All these meticulous care in writing and reviewing will make sure the information integrity part is taken care of!

This document we publish is not our personal work of art. It is a product of collaboration with a purpose. Our sense of ownership to this book ends with making sure we write the right content. When there are issues in the book, this sense of ownership must not interfere with performing our responsibility of fixing the issue.

Right Information at the Right Time

The right word, rather the right information at the right time, right where they are looking for, can make a positive difference to the user. Your user can be a seasoned administrator in a data center, or if you are writing for medical equipment, professional ultra sound technician, or an Ikea customer who is trying to assemble a kitchen sideboard. Understanding what they need when they come to the user guide and giving them exactly that is your success as a writer.

I started my day with listening to a SDL Webinar on content strategy and customer focus. And how VMware improved customer experience with a new content strategy. It was very clear that the presenter had a clear plan and worked on executing the plan for successful implementation. After the webinar, shared the following notes with my colleagues at work:

• Provide information to the customers in their language
• Make sure your content finds your customers (make sure content is available in all channels they frequently use) 
•  Personalize and customize the content experience to meet specific needs of your user (Products, customers and requirements are all different. Understand the differences and cater to the requirement)
• Make sure tech writers interact with customers, support folks, TMEs and PM along with Engineering and QA
•  Don’t assume what your customers need. Customers do not fit into buckets. Ask them what they need.
•  Ask customers what kind of videos will help them. Produce prototypes and circulate. Take customer feedback then produce real videos.
• Use analytics to understand content usage.
• Make sure your content is easily retrievable. Use the following:

o   Structure content

o   Improve meta date

o   Optimize your content for Search

• When you make customer contact, have a goal and meet your goals in that meeting. (Ask right questions, provide examples and prototypes)

• Sit with support folks when they are taking customer calls. Listen to the customer questions and how support is finding information.

 Sitting at my desk now, after initiating the publication process for my document and while waiting for the document to show up online, I am thinking back on the how documentation plays a pivotal role in determining the products usability. And where we should be focusing on while creating the pieces of information that we string together for a document. The means of making content reach the customers at the right time.

I think knowing our audience, interacting with them on their requirements and designing a content strategy and content delivery channel is of utmost importance in your career as a technical writer. So when you set up that meeting with your development folks to document a feature, start with this questions such as the following:

• How does the user interact with this feature?
• Is this part of a bigger process?
• What do  they need to know when they work on this feature?
• Is there something they should or should not do with this feature?

When you ask these questions and go back to the test environment and play around the product, imagining yourself as the user, you will understand the product from the user’s perspective. So when you interact with your user or customer, you are able to ask the right questions about their pain points with the product. The usability and user experience teams are trying to make every product simple and easy to use. But there will always be a level of complexity in the product that only documentation can explain. This is how documentation or content is considered a business asset.

Role of Documentation

What is the role of documentation in development – any development?  Hardware, Software, Manufacturing, Communication – you name it.

What do you do when your child opens a birthday gift, lets say, a new board game for your family, called Great States. You haven’t seen in before. How do you play with your child? Have you ever looked at the instruction sheet that comes with such board games? You are driving your car. Suddenly notice a little orange thing flash in the dashboard. Have you ever searched for the manual in the glove compartment and found it was the tire air pressure monitor? How do you assemble that book shelf you ordered online from Costco? Do you intuitively know which piece of wood goes where? (Even with the drawing and instructions, we assembled our top shelf upside down and are living with it.)

OK – now you are on Amazon.com or on Schoology. Trying to purchase something or setting up your child’s account. You have no idea how to add the teacher as a coach on schoology. its late and you don't have time to call the teacher to ask how. Do you look for a little Help icon or a question mark and click to read what are you supposed to do here?

You just bought a new printer. You are no techie. You need to install the printer so you can print some of the recipes you found online. What do you do? Have you flipped through the instructions? or searched online for a specific model number and downloaded a PDF doc?

How do you think all these information are made available to you? Somewhere someone, called a technical writer, looks at these products, talks about these products, use these products and writes about them. So when you need to know what to do, the paper or the web page called ‘Help pages’ are there for you.

The role of documentation may be very little. But it is a tiny little piece in a bigger puzzle. Without the tiny little piece, the puzzle is not complete. The missing piece will create a visible tiny little hole, that may become a gaping gap when pieces all around it start to loosen up and fall.

Change

"This is how we do it. Just follow what's there". "This is the way its done here. You will not be able to convince everybody to change anything, so just do it." "We do not have the time to change, lets do it the same way its done. We can change it later". Sounds familiar?

Often times, at work or in the kitchen, there is always a true and tried recipe to do something. When we follow the recipe, we can always emerge flawlessly successful, on time. And yes everyone will appreciate it. Consider pancakes. Mix in one egg, half cup milk and 1 cup of bisquick. Sprinkle some chocolate chips on top. Done. Your kids love it on a Sunday morning. Its true and tried. No changes required. Right? Wrong.

The kids are used to the chocolate chip pancake you make. It is easy and convenient for you to make. You are used to making it that way. And they are used to eating it that way. They are not familiar with any other option. So until the law of diminishing marginal utility sets it, you are good to go.

Sometimes, doing the same thing over and over again can cause a mental fatigue. You have this intense urge to change something. You don't know if its going to be for better or worse. You won't know until you try. So yes, I did it in the kitchen this morning. Sunday morning pancake with a little twist. A mix of cinnamon, cardamom and brown sugar. And yes, the kids loved it. (Though I didn't). Now they know a different flavor. And are willing to try new mode of pan cake presentation.

Now, lets think about the documentation. We sometimes tend to follow what was true and tried 10 years ago or even five years ago. But in the world of technology, is everything the same? Are we accessing data in the same speed as we did five years ago? We need instant gratification with instagram. So do we have room to try out different methods of presenting information? We need the following:

- Accuracy - Egg
- Simplicity - Milk
- Accessibility - Flour

How we present it, what we add to accentuate the flavor is within us. Our customers would not know what is possible and available until we provide it to them.

Someone suggested calling 'documentation' as 'product information'. How very apt! When we look at the product from 'documentation' perspective we are removed from the product and approach is as an outsider. Instead, when we consider ourselves as product information folks, we may look at the product in a different perspective. And that perspective might change what we write, and how write or even how we present the information.

Everything needs a triggering point, The change. The willingness to think beyond deadlines.

Content Strategy

What is Content Strategy? To quote Content Wrangler: “Content Strategy is the analysis and planning to develop repeatable system that governs the management of content throughout the entire content life cycle.” We are technical writers. Why do we need a content strategy? We are only documenting a product and features for people to use. Is it not enough if we just focus on making It simple and readable? Here I borrow from Content Wrangler again – “Provides context, so that the organizations vision can be implemented in an integrated way to meet business goals and project objectives.”

Business goals and project objectives are the key terms. What we are writing here should integrate well with the product to meet the business goals of helping and retaining customers. Project objective goes beyond on time delivery of content. We need to maintain the content for patches, upcoming releases and may be new products that the business unit builds based on this product we are working on.

Anytime we start on a new project, or jump into writing for an existing project, before getting started with the feature, consider doing the following:

•  Look at the product. If you can watch a demo, great. Understand the reach of the product the expected or existing customer base.
•  Understand the impact to the other products around this one. How this product relates to other products in the same business unit or company.
• Talk to the PM. Ask what is the long term goal for the product.
• Wait – you are not ready to reach out to the SME for tech TOI yet!
• Then –

o   If it is an existing, mature product, analyze the existing content. Understand the plan behind the organization. See how you can leverage this existing organization to meet the goals you understand for the product.

o   If it is a new product, discuss and plan on the kind of information the users would need (Your document deliverables).

• -          Now do the following:

o   Plan content for reuse between deliverables.

o   Setup folders and file names in your CMS for easy identification and usage between writers.

o   Think task based minimalism and plan topics for deliverables.

o   Make sure to follow your organizations guidelines for titles and style

o   See if you have to localize your content in future. If that is the case, make sure to be consistent in your language usage to improve cost efficiency by building a healthy translation memory.

Think of the long term impact when you plan for short term deliverables, depending on the technology, market, consumers and language.

Documentation and Customer Experience

Before thinking about your content strategy and architecting your information, talking to few of your cross functional folks and asking relevant questions might help to meet your customer needs in your documents.

Meet the Product Manager -  Ask to see the Product Requirement Definition. (PRD). Discuss the must have, good to have or nice to have features in plan for the product. Ask how these features are going to enhance, complement or replace any existing product in the market or feature in your product.

Talk to the Development Manager - Ask what is their plan for development. Agile? Waterfall? How do they track the features? Do they have an evolving functional spec? Or are they setting things on stone before beginning development? How do you want to integrate document for this product. Are you considering integrated content, in-product documentation or a set of hybrid documents? How complex are the features? Do you want video documentation?

Discuss with the QA Manager - What is the plan to test?  Can they give you access to the test environment? Most of the time QA folks find the issues and glitches in the product and can help you with those information. You have to document these as warnings/guidelines/recommendation or limitations for your customers. Ensure to involve them in the review process.

Talk to the TME - TMEs and Technical/Customer Support people are the closest you can get with the customers in your organization. Plan a meeting with the TME, request to understand how a typical customer approaches the product. What do the customer look for in the docs? Discuss the types of document that'll be helpful on the field. Based on this you can come up with list of docs you must write, need to write and may write and prioritize.

Talk to your Documentation Manager - Plan for right kind of writing support. Plan and start working on the product, or if its a hardware play around with it to understand the components. Write, get reviewed, edit, rewrite and publish.

Talk to Technical/Customer Support Engineers - After you write, get reviewed, post and when the users start using the product, find the Technical Support engineer for your product. Sit with them. Ask if they use your documentation at any point to answer support calls. Are they able to find the answers your customers and they want to find. If not, ask what would be helpful.

Along with all these, if you can get access to your actual typical customer, ask them, how you, the technical writer can help them better.

The role of documentation in a product's customer experience is unique. If the product is absolutely no brainer, no one looks for that Help icon or google for additional information. When the product is complex, and someone is trying to figure out something, they do look for that question mark and click on it, with a hope to find what they are looking for. It is our job to anticipate, work on it and give it there.

User Focused Documentation

"This Installation Guide looks interesting....would make a good travel companion." "What a great User's Manual, a must read for all administrators" If you are reading this, you are probably thinking that I am crazy and almost going to close this window. Not yet :) Just give me a couple of more minutes here. I am with you as well! No one wants to read a technical document for pleasure. The one and only purpose you, me or anyone would even care to click on that Help icon on the screen or open a PDF, is to accomplish a task that we need some help with. A task that is not really intuitive or complex enough that needs some additional help to complete.

So how do we plan and write our documentation to cater to their needs? Our engineering teams are distributed globally. If we are lucky we get some ideas about the product in development. One fine day someone gives us a functional spec and may be a piece of hardware or a software to try out and write. And we write. We definitely try to use the product, think about how it works, imagine a real life situation and write what we understand. We do make sure that its technically accurate.

But how does that apply to the user? Is the user able to get what they want from a document that is technically accurate but does not give them the support they want? We don't want someone to read a document and call customer support to figure out what's written in the document.

I think asking the following five questions would enable us to focus on the user who will actually need some help at some point when they in the process of using this product:

Who is our audience? Does this product cater to beginner level users or advanced administrators? Having an answer to the who will help us to plan the document.

What do they know about this product? Are we writing for a product that is already available? is this a brand new technology? This helps us to plan how much conceptual information we want to provide.

Why will they need this document? An answer to this question enables us to plan the documents we need to write. Are they looking install, configure or upgrade something? if all these are intuitive, are they looking to use this product?

When would they need this document? Will they need it as they use this product? Before or after installing? the Why and When might look similar, but this when helps you with Information Architecture. You can decide if you want to provide an Online Help system or a Quick Start guide based on the answer to this When.

How will you know the users and product? Are you only talking to the developers working in their feature silos? Working with Product Management or Marketing? Are you able to meet with the actual users to understand their needs? Or do you have access to the teams within your organization that directly work with the users/customers?

Tools and Processes may vary, they way we deliver information may vary, but if we can find the right answers to these five questions, we will definitely be able to provide user focused document that will actually help the customers.