The state of equilibrium: Balancing the voice of the application and the voice of the customer

  • Article

When we consider which terms and words to use in Microsoft Dynamics AX product content, such as on the user interface, in the glossary, in error messages, in help topics, in white papers, and so on, we must continuously deliberate the two relationships of key elements that are inextricably linked:

  • Voice and the audience.

– and –

  • Application and the customer.

What is voice?

From a grammar aspect, voice refers to the classification of a verb form that indicates whether the subject acts or whether the subject is acted upon. In the active voice, it is the subject that performs an action. In the passive voice, it is the subject that receives the action that is performed.

Examples of voice:

  • Active voice: Phyllis applies the factor 100 to convert the amount from the quotation currency unit to the base currency unit.
  • Passive voice: The factor 100 was applied by Phyllis to convert the amount from the quotation currency unit to the base currency unit.

From a communication aspect, voice represents an expression of how the writer communicates the subject matter or how the writer communicates to the audience. This aspect of voice requires tone.

For example:

  • In an application message, you may see a sentence, such as: The field Preparer is required. This sentence uses the passive voice, describes the result of an action as an application requirement, and it omits a naturally conversational tone.

If we were to rewrite this sentence to consider active voice and a naturally conversational tone, it might read: The person is not assigned to a user role.

  • In an error message, you may see a sentence, such as: A purchase order change was initiated against a purchase order in the new fiscal year before the purchase order had been processed through year-end . This sentence is complex, lacks clarity and simplicity, uses the passive voice, describes an activity that occurs inside of the application, and it omits domain-specific terms and a naturally conversational tone.

If we were to rewrite this sentence to consider active voice, clarity, simplicity, precise and accurate domain terms, and a conversational tone, the error message might read: A purchase order cannot be changed when the confirmed date is not in the current fiscal year and the journalizing date is in the current fiscal year. Either set the transaction accounting date to a date in the prior fiscal year, or perform the encumbrance year-end procedure.  

What is tone?

Tone is a writing technique that supplements voice. The tone of any content is generally defined as the particular style of writing that expresses the writer’s attitude to the subject matter or to the audience. 

The tone of product content can take many forms—formal, informal, technical, conversational, colloquial, idiomatic, jargon, metaphoric, and so on.

Depending on the content type, for example, user interface, error messages, glossary, help topics, or white papers, the tone of the product content may change. For example, the syntax, diction, depth or breadth of content, or clarity might change to illustrate a point.

For example:

  • Not enough rights to use table <table name>. The tone is Informal, technical, and colloquial.
  • You are not authorized to access table <table name>. Contact your system administrator. The tone is formal and naturally conversational.

Tone is critical with respect to voice because it represents how we communicate with our audience, yet it is the audience that determines tone. The key to determining which tone we apply consistently to product content requires us to know who our audience is.

Audience

Quantitative and qualitative research studies of our user audience validate that the Microsoft Dynamics AX audience comprises partners and customers that work in various industries, domains, roles, and locales.

For example, with respect to our terminology work, we have survey information about who the consumers of product content are. We have demographic information that documents where geographically they are, their education, and what activities they perform when they use the Microsoft Dynamics AX product. And we have information about what they expect, what they want, their intents, and what they need with respect to glossary content. (For more information about the Microsoft Dynamics AX terminology surveys, see my earlier blog entry, When is good enough good enough?).

Combining the voice and audience elements

When we consider the diversity of the Microsoft Dynamics AX audience and the industries, domains, roles, and locales that the product serves, we must assess which voice to offer consistently in product content. But more importantly, we must acknowledge that there are traditionally two voices in this equation—the voice of the application and the voice of the customer—that we must satisfy with one voice.

Because the Microsoft Dynamics AX product supports many industries and domains that have been in existence for a very long time, such as accounting, which has been in existence from at least the 13th century A.D., we cannot select arbitrary terms or make up the terms that appear in the product content. We must use the vocabulary of well-established industries and domains. If we do not, or if the product design does not align with the domains, then we end up creating a small-group vocabulary, and we alienate all others. To support such vocabularies, we end up creating neologisms. Two examples of neologisms are financial inventory, and its complementary phrase, post financial inventory.

During the product design phase, we focus on product content, most specifically glossary entries and user interface content. The concepts and terms that we introduce in the Microsoft Dynamics AX product are required to be precise and accurate with respect to their domains and they must remain resilient release over release. The terms that we use to name concepts are the same terms that are used in the user interface and subsequently in written content.

(For more information about how we select terms that appear in the user interface, see my earlier blog entry, The origin of Microsoft Dynamics AX glossary entries.)

While the domain informs the terms we use, our tone does not have to be inflexible. It does, however, need to be clear, precise, and accurate so that that it is understandable and translatable. A voice and tone that embrace formal, clear, simple sentence structure (subject-verb-object), a naturally conversational tone, and term choices that map to industries and domains enable the multinational audience that Microsoft Dynamics AX serves.

How we write

The key to writing product content is that product content should complement the precise and accurate terms that the domain demands while be presented in an accurate, appropriate, naturally conversational voice.

A naturally conversational voice is a technique that combines the tones we use in writing and in speaking. A naturally conversational voice should be accurate, and it should be clear and as simple as possible, for example, in its grammatical structure. It should sound natural, not forced.

And the product content should be focused on the intention of the partner or customer—what the user wants to do—not what the application can do for the partner or customer.

For example, product content, such as on the user interface, should be clear and consistent. It should not describe objects that exist inside of the application or computer and outside of the application or computer, nor should it describe activities that are performed on these objects. For example, to use the wording Create a customer refers to an activity that is performed on an object that exists inside of the application or computer. This phrasing is not accurate, nor is it clear or simple. The activity is adding a registration to a customer directory; customers are not created, and records are added to a database.

When we combine the aspects of voice, tone, and audience with a product deliverable, we define a consistent voice for our product. For example, the following error message combines the aspects of voice in that it follows established grammar, syntax, and punctuation rules; of tone in that it is conversational; of audience in that it is clear and simple, and it uses domain terms precisely and accurately with respect to the domain.

  • The form cannot be closed because the distributed amount <amount> does not equal to the source document amount <amount>. Select the source document amount, and modify the accounting distribution amounts so that the distributed amount equals the source document amount.

How we align the voice of the application and the voice of the customer

The key to aligning the voice of the application and the voice of the customer is in the documentation of objective, measurable writing guidelines. It is against sets of guidelines that product content can be evaluated and measured with respect to voice and tone.

Guidelines should identify the principle aspects that should be documented with respect to audience, and they should offer patterns for how to document these principle aspects. The aspects that are selected should be qualitative, not subjective. The patterns that are established should incorporate the components of voice and tone. For example, we know that partners and customers use the Microsoft Dynamics AX product to perform activities, whether they are designing a form or adding a sales order to the database. And we know that in order to perform an activity, there needs to be an object of work, a subject, and one or more tools.  

So the guidelines that are documented should identify these four aspects, and they should offer patterns for how to write about activities, the object of work, the subject, and the tools. These patterns should include voice and tone considerations. Where one product content type may be considered, say for example, the user interface, then only the pattern for that product content type should be applied.

For the purpose of ensuring consistency in voice and tone across the application and across all product content, guidelines should be objective and be measurable.

A robust, accurate product glossary and prescribed, measurable writing guidance for wording patterns enables anyone writing product content for the user interface, the glossary, error messages, help topics, white papers, and so on. These practices help to align phrasing and sentence structure and to inform grammatical structures, voice, and tone. Such practices enable stakeholders to introduce, measure, and sustain the consistency and quality of product content.

For information about measuring the quality of contributions, see my earlier blog entry, Measuring the quality of content submissions. While the primary focus of this blog entry is on glossary entries, the practice I discuss in this blog entry is applicable to all product content that we deliver.

Microsoft Dynamics AX glossary

I invite you to peruse the Microsoft Dynamics AX glossary to see examples of how we use voice and tone in context of the application and our audience. And I invite you to offer your observations on our use of voice and tone with respect to the audience.