How to Repurpose IT Documentation and Get Away with It: Consistency in Voice

We’ve all been there: a customer is looking for documentation that you just don’t have readily available. Then the idea strikes that you can simply reuse some documentation created for a previous project or repurpose vendor product documentation to meet your customer’s specific needs. But as someone who has been on both sides as a consultant and a customer, I can promise you that customers can tell when you’ve copied and pasted material.

When you do, customers will take your presentation and your recommendations as a professional less seriously. Nobody likes to feel like they’re being served reheated leftovers, and our customers are no different.

Discover how CDW can assist you with your ServiceNow needs.

I had an IT project manager as a client who confided in me that he was quite familiar with our products’ documentation and would cast aside any documents provided to him that were similar in broad strokes to documents he had already seen. Many of our customers in ServiceNow Solutions do plenty of research on their own about ServiceNow as a platform before we ever talk to them. It’s our job as IT consultants to ensure that the documents we provide bring value that’s specific to their needs, beyond what a visit to any internal wiki or a Google search can offer.

But how can they tell? They know because of the inherent inconsistency of written voice in a document that’s been compiled from multiple primary and secondary sources. This blog post will describe what written voice is and how to maximize the impact of both business and technical writing by using a consistent written voice.

What Is Written Voice, and Why Does It Matter?

The written voice is the author’s style, a personification of his or her personality in a written work. While Writer’s Digest defines written voice as, “The rhetorical mixture of vocabulary, tone, point of view, and syntax that makes phrases, sentences, and paragraphs flow in a particular manner,” you can think of it simply as the subtle signals in your document that someone picks up on that lets them know you are the one that wrote it.

When a document’s written voice is inconsistent, it becomes much harder for your customers to read as they navigate through multiple disjointed voices. Having multiple voices throughout a document is also a dead giveaway that it’s a Frankenstein’s monster of other people’s work.

The best way to improve this is also the easiest: Read your work back to yourself (out loud is best), and note where you trip over words or when your reading flow is broken — there’s a good chance you’ve encountered an inconsistent voice.

As you read through something you’ve written, ask yourself the following questions about each of the four pillars of the written voice:

Vocabulary

• Does my document refer to technology or applications by the same names throughout? (For example, referring to the “ServiceNow Platform” as “Service Now” or “Now Platform” at different points in your document.) Using multiple names for the same technology in one document confuses readers.
• Does my document consistently use terminology that’s specific to my customer? (For example, referring to a different customer’s organization or specific team name that’s not relevant to the new customer for whom your document is prepared.) Accidentally leaving an old customers name, brand imagery or internal terminology in your document will confuse your new customer and make it obvious you’ve copied someone else’s homework.

I recently worked with a client in the cosmetics industry; a company full of artful, creative people. Our project stakeholders asked us to provide extensive training documentation and visual diagrams of business processes to them. They were delighted when, at the end of the project, all the documentation we created for them was fully branded with their unique terminology, with color schemes and logos copied directly from their marketing guidelines.

This drastically sped up the adoption rates for their new technology, because they could roll out their training documents as written to their end-users, and their creative leadership team was able to understand the content of each presentation without having to translate everything mentally through their company-specific visual language.

Tone

• Does my document use the same written tone — such as formal or informal voice — throughout? Examples include use of humor, emotional language, acronyms and contractions such as “cannot” versus “can’t.” Switching back and forth between a formal and informal tone is a sign that the document has been copied and pasted. Often, copied sections of technical documents are written in a formal tone, while the bits of content we add after the fact are written in a more natural, informal tone.

Refer to the chart below for help in determining whether your writing is in a formal or informal tone:

Point of View (POV)

• Does my document use the same point of view (For example, first, second or third Person POV) throughout? Use the descriptions below of each point of view to determine which is right for your document:

First Person POV: You are the “main character” of the document, and the document is written from your personal perspective. In first person, you can make use of personal pronouns such as “I,” “we” and “you.” First person POV should be reserved for documents that are based on personal thoughts and opinions, or if you are describing actions you’ve personally taken.

Second Person POV: You are writing to a specific audience, and the document is written for a specific audience to consume. In second person, you can make use of the personal pronouns “you” and “yours,” but should not refer to yourself as the author using “I” or “we” pronouns. Second person POV is the most common and most appropriate for business writing to a non-technical audience.

Third Person POV: Your document is written from the POV of an external narrator not directly connected to the audience. In third person, you can make use of singular or plural pronouns such as “he,” “she,” “they,” etc., but should not use any personal pronouns such as “I,” “we,” or “you.” Third person POV is most effective when used for impersonal, technical documentation not intended for a specific business audience.

Many of the customers we interact with as IT professionals are non-IT staff, who may not often interact with technology. Nothing repels them faster than sterile, overly technical descriptions that don’t include specific calls to action for their role.

Syntax

Syntax is the most important, and poorly understood, part of consistent written communication. Syntax is defined as the way in which words are put together to form phrases or sentences, but you should consider syntax more broadly as the overall structure of your document and its formatting. Ask yourself the following:

• Does my document follow consistent formatting throughout for the following?
  • Lists: All lists should have matching formatting, including the same list icons (bullets vs. numbered lists).
  • Font: The entire document should have the same font choice for all body text and should be the same size across all paragraphs and headers.
  • Margins and indents: The entire document should be aligned to the same margins, on both left and right sides. Indents should be consistently applied to each paragraph.
• Is my document free of grammatical mistakes?
  • Punctuation: Each sentence of the document ends in some form of punctuation.
  • Mixed Tense: The entire document should be written in the past, present or future tense throughout.
  • Spelling: Nothing breaks a reader’s flow like an obvious spelling error.

Summary

Taking the time to review and copy edit your documentation may seem like a waste of resources, but the return on investment is not so easy to measure. The value in well-formatted and consistent business writing is in the unspoken, often immeasurable considerations your customer makes as they read through a written work.

Small errors and inconsistencies add up in customer perceptions and undermine the value of the important information you’re delivering. Learning about your unique written voice or that of your organization and using that voice consistently will build trust and confidence in your customers so that when you speak, they listen!