Further, product content should distinguish principle objects of work from surrogate objects of work. Otherwise, when we do not, we deliver an application that does not align with the industries and domains that we support, and we create a small-group vocabulary, including neologisms, that is understood by only a very few people.

An object of work is an entity, that is, an object that can be uniquely identified. Any one activity is directed towards one or more objects of work. Some activities are directed towards objects of work performed outside of the application, and we call these principle objects of work. Some activities are directed towards objects of work performed inside of the application, and we call these surrogate objects of work. You can think of an object of work as providing the motive for action, for example, as the motivation for an employee to perform an activity or a set of activities in order to meet a strategic organizational objective.

Say, for example, a production manager is assigned an activity to produce a widget. His high-level activity comprises the following tasks:

1. Research how to produce a widget. [an object of work outside of the application]
2. Register information about the participants and resources that participate in a production activity. [an object of work inside of the application]
3. Allocate budget funds to pay for planned production activities. [an object of work inside of the application]
4. Schedule resources to produce a widget. [an object of work inside of the application]
5. Produce a widget. [an object of work outside of the application]

In this example, we separate the tasks that support the principle objects of work that occur outside of the application from those tasks that support the surrogate objects of work that occur inside of the application, and we document each task in context of its object of work by using precise and accurate terms and verbs with respect to the domain.

As you likely noted, we avoided constructions in the example such as Create a new widget and Enter or view the production because people do not use the application to create, view, or produce a widget; people perform these tasks by using tools other than the Microsoft Dynamics AX application. So we know that the task of producing a widget occurs outside of the application. The application supports tasks such as registering information about the participants, resources, and artifacts of the production activity and registering information about the production events as the widget is moved and transformed through different stages of the production process.

In this blog entry I focus on how we frame objects of work, and I offer considerations for thinking about and for writing content about the principle objects of work that live outside of the application and the surrogate objects of work that live inside of the application, the subjects that perform work activities, and the tools that the subjects use.

The relationship of objects to roles

When we consider an object of work, we need to consider the role of an object so that we can accurately determine whether the activity occurs outside of the application or inside of the application. An object of work can be further refined to distinguish an entity as concrete or abstract, for example, an object of work can be a person, place, thing, a social abstraction, such as a goal or a claim, or a mental abstraction, such as knowledge.

These distinguishing characteristics inform the structure of the product content and inform the term and verb choices we make. The verbs we choose are as important as the terms we choose because verbs are the cues that indicate the action of the role of the object of work. The verb communicates whether a task supports an object of work that is performed outside of the application or inside of the application. For example, we would use the verb recruit to name an activity that occurs outside of the application, and we would use the verb register to name an activity that occurs inside of the application.

The following examples clarify the concept of a role in the context of an object of work.

In the real-world domain, each object assumes a role in a relationship:

In a computer application information schema, each object is represented as an entity type that is assigned a role type in a relationship type:

When we combine these concepts, then we end up with a scenario that documents a real-world domain aspect of principle objects of work that exist outside of the application and surrogate objects of work that exist inside of the application. For example, the following conceptual object model elaborates an employment role relationship aspect. Note that it does not consider other aspects, such as the tax or legal aspect.

A sentence that describes the preceding model, such as An organization assumes an employer role when it participates in an employment relationship with a person who assumes the employee role, does not mix the vocabularies of the principle object of work that lives outside of the application (domain vocabulary) with the surrogate object of work that lives inside of the application (a tool-dependent vocabulary). Instead it uses a domain vocabulary to document the roles between an organization and a person and the relationship between an employer and an employee.

We can apply this approach of distinguishing roles of objects of work to the earlier example of the production manager who is assigned an activity to produce a widget. We note that the production manager participates in tasks that require him to participate in a role of employee but that require him to perform tasks in which the roles of the objects of work differ: outside of the application (research, produce) and inside of the application (register, schedule). While the unique roles of the objects of work are not interchangeable, the role assignments sometimes occur synchronously. For example, a widget may be participating in the production process (outside of the application) while the production manager is registering its stage of production (inside of the application).

Framing the writing solution

How do we write product content that distinguishes the principle objects of work that live outside of the application from the surrogate objects of work that live inside of the application?

It seems that the essential considerations with respect to writing product content that distinguishes principle and surrogate objects of work are:

• The activity and its tasks.
• The location of the activity and its tasks.
• Needs of industry, domain, role, and locale.
• Satisfying work context, audience, and voice considerations.

At a more granular level, we then consider the roles of objects of work in an activity—those outside of and inside of the application. These considerations together inform term and verb choices. Some basic questions to keep in mind when considering how to write about the activities with respect to the roles of the objects of work include:

• What is the assigned activity?

An activity is a functional work structure in which one or more persons and pieces of equipment participate and in which resources are consumed, produced, and used. An activity can be decomposed into tasks. An activity is participation-centered no matter whether it is performed to produce a principle object of work or a surrogate object of work.

One activity is distinguished from another by its object of work.

Example:  Claire manages the hiring process.

• Activity 1: Claire conducts an interview with an interviewee.
• Activity 2: Claire registers an interviewee by using the Microsoft Dynamics AX application.
• What is the object of work?

The object of work is the specific concrete or abstract entity, such as a person, place, thing, goal, or knowledge. In this example, the high-level object is work is to manage the hiring process. The object of work provides the goal for Claire’s activities – to conduct an interview and to register the interviewee by using the Microsoft Dynamics AX application.

Example: Claire manages the hiring process.

• Activity 1: Claire conducts an interview with an interviewee (object of work).
• Activity 2: Claire registers an interviewee (object of work) by using the Microsoft Dynamics AX application.
• Who is the subject performing the activity?

A subject is the person who performs an activity or task. When an activity or task is performed inside of the application, system user is the name of the role to which the person is assigned.

The subject—in this example, Claire—remains the same in both activities.

The relationship between a subject and an object of work is mediated by a tool.

Example: Claire manages the hiring process.

• Activity 1: Claire (subject) conducts an interview with an interviewee (object of work).
• Activity 2: Claire (subject) registers an interviewee (object of work) by using the Microsoft Dynamics AX application.
• Which tools are necessary to perform the activity?

A tool is an instrument, tangible or intangible, that is used in the performance of an activity or an operation. A tool enables the user to interact with or operate on the object of work. More specifically, tools comprise such things as a software application, for example, the Microsoft Dynamics AX application, the work context, and the knowledge that the user possesses about the activity or the process or processes that support the activity.

Example: Claire manages the hiring process.

• Activity 1: Claire (subject) conducts an interview (tool) with an interviewee (object of work).
• Activity 2: Claire (subject) registers an interviewee (object of work) by using the Microsoft Dynamics AX application (tool).

Answers to these questions should inform examples of verbs, terms, and writing patterns and wording conventions that would apply to each context.

While a list of terms, or our product glossary, should remain neutral and constant no matter whether the content documents an activity to support a principle or surrogate object of work, special attention should be paid to the verbs that are used. Some verbs are more appropriate for documenting principle objects of work that occur outside of the application while others are more appropriate for documenting surrogate objects of work that occur inside of the application. For example, verbs such as research and collaborate are generally used to describe activities that a subject performs on a principle object of work outside of an application, while verbs such as add, register, schedule, and submit are generally used to describe activity operations that a system user performs on a surrogate object of work inside of an application and about its aspects of time and state.

An essential set of objective and measurable content guidelines might include:

• A list of verbs used for documenting the role of a principle object of work that participates in an activity outside of the application.

Examples: build, collaborate, learn, produce, research

• A list of verbs used for documenting the role of a surrogate object of work that participates in an activity inside of the application. The list should include verbs that consider aspects of time and state.

Examples: activate, add, approve, authorize, cancel, confirm, delete, edit, generate, journalize, modify, register, schedule, submit, track

• Specific writing patterns and wording conventions to apply when describing a principle object of work that participates in a role outside of the application and to apply when describing a surrogate object of work that participates in a role inside of the application.

  Examples:

  • Pattern: A simple, compound, or complex sentence that incorporates the components of a naturally conversational voice and tone.

  Writing convention: <Subject> <verb> <object>.

   Example:

  • Cassie defines commitment accounting policies and budgetary control policies to enable the organization to track budget allocations and expenditures.
    
  • Pattern: A simple, compound, or complex sentence that includes a prepositional phrase and that incorporates the components of a naturally conversational voice and tone.

  Writing conventions:

  <Verb, imperative mood> a <noun> <prepositional phrase>.

  –or–

  <Subject> <verb> <object> <prepositional phrase>.

  Examples:

  • Transition a sales event to the next stage in the sales qualification process.
  • A vendor supplies products to one or more legal entities in exchange for payment.
    
  • Pattern: A simple sentence, phrase, or tooltip that names a document type.

  Writing convention: <Verb, imperative mood> a <name of the document type>

  Example:

  • Maintain a production order
    
  • Pattern: A simple sentence, phrase, or tooltip that names an event.

  Writing convention: <Verb, imperative mood> a <name of the event>

  Example:

  • Document a sales lead
    
  • Pattern: A simple sentence, phrase, or tooltip that contains an adjective or adjective phrase and that names an event.

  Writing convention: <Verb, imperative mood> <article> <adjective or adjective phrase> <name of event>

  Example:

• Add a new customer registration.

[Note: Imperative mood expresses requests or commands, is always in the present tense, and implies the subject you.]

• Specific considerations for writing content with respect to the diversity of roles in the domain, industries, and the locales that the Microsoft Dynamics AX application supports.

Example: The term organization applies industry-wide; company applies most specifically to the commercial industry.

For more information

For information about content on the user interface, see my earlier blog entry, Content is the user interface.

For information about writing exception messages that use an audience-neutral vocabulary, see my earlier blog entry, Crafting an effective exception message.

For information about writing in a naturally conversational voice, see my earlier blog entry, The state of equilibrium: Balancing the voice of the application and the voice of the customer.

For information about measuring the quality of content, see my earlier blog entry, Measuring the quality of content submissions.

For a general overview of activity theory, see https://www.wordiq.com/definition/Activity_theory.

• Confirmation messages

A confirmation message is displayed to verify whether the user wants to complete an action. For example:

Do you want to save the changes to the customer registration? [Save, Do not save, Cancel]

• Error messages

An error message is displayed when an exceptional condition is met and the application cannot resolve the condition. For example:

You are not authorized to delete user group <name>. Contact the security administrator to resolve this exception.

• Notification messages

A notification message is displayed to communicate the occurrence of an event that a system or user asynchronously sends for receipt. For example:

A workflow work item has been assigned to you.

• Warning messages

A warning message is displayed to communicate a condition that may occur in the future. For example:

If you modify the address on this form, the address registration will need to be updated manually.

Do you want to continue? [Yes, No]

In this blog entry I examine one type of message—the error message. I focus on the structural components of this type of message, and I offer considerations and patterns for writing this type of message.

But first, I propose a class name change to the class of messages that we name error message. While an error message seems to be correctly named when  an exceptional condition occurs with respect to data validation, this type of message seems misnamed as an error message when, from the perspective of the user interface, documentation requirements are not met.

A more accurate name that I propose for this concept and class of messages is exception message. You will note that I use the term exception message throughout this entry to refer to the class of message that is named error message in Microsoft Dynamics AX 2012.

The purpose of an exception message

Exception messages are displayed to the user when an exceptional condition is met and the application cannot resolve the condition.  Ideally no exception message should be displayed. However, when exception messages are displayed, they should be effective.

When I review an exception message, I review it to determine the effectiveness of it with respect to audience and to ensure consistency in the exception messages that are delivered across the application. In my evaluation, I consider the following questions:

• To whom is the exception message written?
• What aspect does the exception message take: an aspect inside of the application code or an aspect of the real world—that is—the experience of the user?
• Is the exception message:
  • Accurate
  • Informative
  • Actionable
  • Grammatically correct
  • Is the exception message written in a naturally conversational voice?
  • Does the exception message contain:
    • An exception statement
    • A cause statement
    • A resolution statement

In the sections that follow, I examine these questions in more depth, and I offer guidance for writing exception messages.

Audience

Anyone who uses the Microsoft Dynamics AX application—partners, developers, customers, customer support professionals—is a candidate for seeing an exception message.

These audiences use the application from two different aspects: an internal aspect, that is, the application code, and an external aspect, that is, the real interaction with the user interface. And each aspect uses a unique vocabulary to communicate. The internal aspect uses a programming language vocabulary, and the external aspect uses a vocabulary of terms and verbs that exist in the real-world domain.

While neither vocabulary on its own is inaccurate, when we consider the diversity of the Microsoft Dynamics AX audience, we must assess how we choose between the vocabularies, voice, and tone in exception messages and how we ensure consistency in exception messages across the application.

We do know that mixing the programming language and domain vocabularies creates a unique small-group vocabulary that alienates more people than it helps because in this small-group vocabulary, we are forced to bridge the communication of complex conditions and concepts by creating neologisms, such as post financial inventory, and nonsensical phrases, such as edit customer.

Given that an exception message is a condition that occurs as a result of an exception to the application code or as a result of a documentation requirement that is not met, they are often first authored by contributors who have deep expertise of the internal workings of the code.  While the exception messages that are written may be technically correct, they generally tend to use the vocabulary of the application code, and that vocabulary does not transfer well to those users who do not have deep expertise in the internal workings of the application. For those audiences whose primary roles include working with the user interface instead of application code, exception messages that favor the vocabulary of the application code do not use a vocabulary that is consistent with the domain nor are they easily understandable to those users who do not have deep expertise in programming languages.

The question I consider in the rest of this blog entry is: How do we write exception messages that address both aspects while maintaining the data necessary to enable the recipient of the exception message to address the exceptional condition that has occurred?

Writing audience-neutral exception messages

If we have to choose one vocabulary for communicating with the various audiences that use the Microsoft Dynamics AX application, it seems we should choose an established, neutral vocabulary. Given that audiences that use the Microsoft Dynamics AX application comprise partners, developers, customers, and customer support professionals who work in various industries, domains, roles, and locales, we should favor the established vocabulary and term choices that exist in the real-world as opposed to that of only one specialized area, such as the application code. And we should focus the exception message on the needs of the person, not on the needs of the application.

If we take a people-focused approach, then audience-neutral exception messages should consider characteristics such as:

• Being user-centric.
• Being actionable.
• Being relevant to real-world industries, domains, roles, and locales.
• Using neutral domain term and verb choices.
• Being naturally conversational.
• Being clear, concise, and consistent.
• Occurring infrequently.
• Not anthropomorphizing the application.

The components of well-constructed exception messages

While an exception message should consider the characteristics offered in the preceding section, it should document the following:

1. The exception – Document that a processing exception occurred.
2. The cause – Document why the processing exception occurred.
3. The resolution – Document a resolution to the processing exception.

Examples of well-constructed exception messages include:

• Project contract number <identification number> does not reference a valid funding source. Select a valid funding source for the project contract.
• The entity type attribute name already exists. Enter a unique entity attribute name.
• The relationship of the person named as the emergency contact to the person named as the employee must be provided. Select a relationship.
• The location that you entered was not found in the reference list of countries and regions. Add the location to the reference list, or select one of the reference country/regions.

The components of poorly constructed exception messages

Exception messages that do not consider characteristics such as those that I offer in the Writing audience-neutral exception messages section tend to be less effective because they often:

• Frustrate the user.
• Describe the processing exception without offering a resolution, describe the processing exception and cause only, or offer only a resolution.
• Offer actions that fail to solve the processing exception.
• Intimidate the user by using a vocabulary that requires deep expertise in application code or use a made-up vocabulary, including terms and verbs, that is understandable to only a small group of people.
• Blame the user for the exceptional condition.
• Use a voice and tone that trivialize the exceptional conditions.
• Contain information that is inaccurate, imprecise, incomplete, or redundant.

Examples of poorly constructed exception messages include:

• The validity of the kanban rule must be within the validity of the related production flow version.

This exception message describes the processing exception from the aspect of the application code and mixes the vocabulary of the application code with the vocabulary of the domain. This exception message does not align terms and verbs accurately with respect to the domain. It does not offer a cause or a resolution to the processing exception.

Corrected exception message: The effective date for a kanban rule cannot be earlier than the effective date of the production flow, and the expiration date of the kanban rule cannot be later than the expiration date of the production flow. Enter an effective date later than or on the production flow effective date, and/or enter an expiration date earlier than or on the production flow expiration date.

• The value <value> in field 'Country/region' is not found in relating table 'Country/region'.

This exception message describes the processing exception from the aspect of the application code. It does not use terms precisely or accurately with respect to the domain, is not audience neutral, nor does it use a naturally conversational voice. It does not offer a resolution to the processing exception.

Corrected exception message: The location that you entered was not found in the reference list of countries and regions. Add the location to the reference list, or select one of the reference country/regions.

• The record may not be deleted. Transitions exist in table ‘Category hierarchy roles’.

This exception message describes the processing exception from the aspect of the application code. It does not use verbs precisely or accurately. It does not offer a cause or a resolution to the processing exception.

Corrected exception message: Category hierarchies cannot be deleted until dependent category hierarchy roles are deleted. Delete dependent category hierarchy roles and try again.

• %(wildcard for datefield) must be later than or equal to the termination date.

This exception message describes the processing exception from the aspect of the application code. It does not use terms precisely or accurately, is not audience neutral, nor does it use a naturally conversational voice. It does not contain an exception statement or a resolution to the processing exception.

Corrected exception message: The position retirement date <date> must be set to a date that is later than or on the employee termination date. Select a later position retirement date.

• A record with RecId <number> does not exist

This exception message describes the processing exception from the aspect of the application code. It uses the vocabulary of the application code, is not audience neutral, and the sentence is not punctuated. It does not offer a cause or a resolution to the processing exception.

Corrected exception message: The purchase requisition number PR-0357911 was not found. Contact the system administrator to resolve this exception.

• Insufficient rights to execute Menu Item Posting.

This exception message describes the processing exception from the aspect of the application code. It does not use terms precisely or accurately, is not audience neutral, nor does it follow sentence-style capitalization guidelines or use a naturally conversational voice. It does not offer a cause or a resolution to the processing exception.

Corrected exception message: You are not authorized to open the Posting form. Contact the security administrator to resolve this problem.

Structural components and writing considerations for exception messages

Addressing how we communicate processing exceptions, their causes, and their resolutions effectively requires us to think about what it is that we communicate in exception messages, how we communicate it, and to whom we communicate it.

In this section, I propose guidelines for writing exception messages. I offer guidelines for identifying the components and characteristics of exception messages, and I offer patterns for structuring and writing exception messages.

A few key considerations for guidelines for structuring and writing exception messages might include:

Structural components

Each exception message should include the following structural components:

• Each component—the processing exception, the cause, the resolution—should be limited to one sentence each.
• The exception statement is required.
• The cause statement is optional.
• The resolution statement is required.
• The exception statement and the cause statement can be combined if necessary to enable the natural flow of the exception message.

Writing considerations

Exception messages should:

• Be user-centered. The exception message should focus on the user’s action and not describe what occurred in the application code.
• Be set in the present tense, use active voice, and use a naturally conversationally tone.
• Use precise and accurate domain-specific terms and verbs.
• Use specific names of resources, events, agents, locations, and the values of the objects that participate in the activity from which the exception message occurred.
• Be context aware and processing context aware. The exception message should present an action that the user can take to resolve the processing exception. If the user is not authorized to resolve the processing exception, the exception message should direct the user to a person who can resolve the processing exception, for example, the security administrator.
• Be relevant to the processing exception that occurred. The exception message should not be vague or attribute human behavior to a condition that occurred in the application code.
• Use complete, grammatically correct sentences that follow the subject-verb-object order.
• The first sentence of an exception message should start with an article, a pronoun, or a noun.
• Use sentence-style capitalization.
• Use punctuation as prescribed in standard grammar books.

Combining the structural components and writing considerations: Patterns

The structural components of an exception message determine format of the pattern. We know we need at least two sentences. The writing considerations offer guidance for the content that appears in the exception message.

Combining the structural components and writing considerations for documenting exception messages informs patterns that can be applied to types of exception messages. For example, a few patterns that might appear in guidelines for writing exception messages might include:

• Pattern: Exception statement. Resolution statement.

Writing convention: <Article, Pronoun, or Noun> <description of processing exception>. <Article, Pronoun, or Noun> <description of resolution>.

• Examples:
• The position retirement date <date> must be set to a date that is later than or on the employee termination date. Select a later position retirement date.
• You are not authorized to add a new active employee registration. Contact the security administrator to resolve this exception.

• Pattern: Exception statement and cause statement. Resolution statement.

Writing convention: <Article, Pronoun, or Noun> <description of processing exception> because <article, pronoun, or noun> <description of cause>. <Article or Pronoun> <description of resolution>.

• Example:
• The form cannot be closed because the distributed amount <monetary amount> does not equal the source document amount <monetary amount>. Select the source document amount and modify the accounting distribution amounts so that the distributed amount equals the source document amount.
  
  
• Pattern: Exception statement. Cause statement. Resolution statement.

Writing convention: <Article, Pronoun, or Noun> <description of processing exception>. <Article, Pronoun, or Noun> <description of cause>. <Article or Pronoun> <description of resolution>.

• Example:
• The entered or selected product is classified as a <product classification>. A subcontracting service must be classified as a service. Enter or select a product that is classified as a service.
  
  
• Pattern: Delete data entity.

Writing convention: ‘<Table label1>’ cannot be deleted until dependent ‘+ tolower( <table label2>) +’  are deleted. Delete dependent ‘+ tolower(<table label2>) + ‘ and try again.

• Example:
• Category hierarchies cannot be deleted until dependent category hierarchy roles are deleted. Delete dependent category hierarchy roles and try again.
  
  
• Pattern:  Internal data consistency processing exception.

Writing convention: The <table.singularlabel> number <identification number> was not found. Contact the system administrator to resolve this exception.

• Example:
• The promissory note number ABC-13579 was not found. Contact the system administrator to resolve this exception.

For more information

For information about content on the user interface, see my earlier blog entry, Content is the user interface.

For information about writing in a naturally conversational voice, see my earlier blog entry, The state of equilibrium: Balancing the voice of the application and the voice of the customer.

To start, I offer examples in different contexts for consideration.

Context 1: Documents, registrations, activities, and people

Does a user really own, documents, registrations, or people?

It seems that all data is owned by an organization, such as a company or a government organization. The individual user of an application, such as the Microsoft Dynamics AX application, is assigned duties that transfer responsibility and control of this data that is owned by an organization. This user is held responsible for the outcome of that control.

Here are a few specific examples of user interface content for consideration:

• My open purchase orders

If I add a purchase order to Microsoft Dynamics AX, it is really my purchase order?

It seems more accurate to state that a purchase order is added to the system, recorded in a database, and assigned a status of open by an administration process that closes the purchase order when purchase events and purchase quantities are matched with payment request (vendor invoice) events and quantities.

• My expiring project quotations

If my job requires me to maintain and monitor project quotations, are the project quotations or their statuses really mine, or are they are my responsibility?

It seems more accurate to state that the responsibility of maintaining a project quotation and monitoring its status are assigned to me.

• My activities past due

If my job requires me to perform tasks and those tasks comprise a task or sets of tasks that can be performed by me, my manager, or any person who shares the same access control permissions as I do, are the activities really mine?

It seems more accurate to state that there are tasks that I have been assigned that are not complete.

• My active leads

If my job requires me to identify leads, are these people and organizations really mine?

It seems more accurate to state that I have been assigned the responsibility for documenting the participants and consequences of a potential sales event and that I am responsible for transitioning the documents to the next stage in the sales qualification process.

• My employees

–and–

• Purchase requisitions for my direct reports

If my job requires me to manage people, do the people I manage belong to me, or does any data about them belong to me?

It seems more accurate to state that employees report to me.

• Enter your name

If I am a user of an application, and I see a field labeled Name and a description of that field that reads Enter your name, what name is it that I enter? Is it my name? Or is it the name of the person or organization that I am authorized to perform tasks on behalf of?

It seems more accurate to state Enter the name of the person or organization.

Context 2: Data ownership and control

Does a user really own the data about himself that he adds to a system that is owned by an organization, or does the user simply have control of it?

For example:

• My information (in context of selecting options for workflow notifications, for example)

If I personalize the product for my use, is the personalization really mine?

It seems more accurate to state that I activated a workflow rule or set of rules based on my preferences. The workflow process, features, policies, and rules are owned by the organization that owns the application.

• My information (in the context of adding data about an employee to the system, for example)

While this context covers many aspects, including legal ones, it seems as though for at least one aspect, some data that is unique to an employee is owned by the organization, for example, my employee identification number. With respect to a government-issued identification number, it seems that while my government-issued identification number is unique to me, the number is owned by the government organization that issued it.

It seems that it might be more accurate to state that the rights to use and access this data are controlled by me.

Beyond a personalized content style

When an employee works in an organization, all data in an application, such as the Microsoft Dynamics AX application, is most often owned by the organization. The employee is granted responsibility and control over data that is owned by the organization.

Using personal pronouns in the objective case, such as you or me, or pronouns in the possessive case, such as my, mine, or your, in content such as the user interface introduces inaccuracies, particularly with respect to questions of ownership, responsibility, and control. In addition, using personal pronouns in the possessive case seems to omit consideration of scenarios in which a user may perform tasks for others, for example, in the case of administrative professionals who support teams of managers or people managers who may perform tasks on behalf of the people who report to them.

It seems that a practice that encourages accuracy and the development of neutral content in an application that does not assume user ownership is more scalable, configurable, and applicable in all work contexts.

Additional considerations for writing content should include writing about the application, the processes that the application supports, and the activities that are performed by users of the application. For example, content for the user interface should consider:

• The scope of a user’s responsibility.
• The point at which a user is responsible for data and artifacts and to whom control of the integrity of the data in the system is transferred.
• The point at which a user transfers the responsibility and control for the integrity of the data in the system to another user.

If a personalized content style is required

If we do not develop neutral content in an application, and we include pronouns in the possessive case, such as my or your, it makes it challenging to write intelligible and clear content when we need to document an activity that references fields, descriptive content, or other artifacts that contain such pronouns. Such pronouns introduce an awkwardness that we must write around. Otherwise, we end up with sentences like: You can use the My approvals page to approved submitted expense reports.

To write around the use of pronouns in the possessive case to ensure accurate user interface text, we would have to use verbs that expressed past events (verbs generally ending in –ed), as opposed to verbs in the present tense, and the text would need to include the prepositional phrase by me or to me. For example: Approved by me or Assigned to me.

However, this construction, while grammatically correct, offers its own set of writing challenges. For example, the following sentence reads as ambiguously as the My <x> constructions, and it is not clear: Select the Approved by me menu item.

If we need to personalize items in the user interface, it seems we might consider a wording pattern, such as: <Verb, past tense> <by or to> <registered user name>. For example:

• Assigned to  Maddalena
• Downloaded by Phaedrus
• Select the Approved by Dante menu item

However, such an approach to personalization, while grammatically correct and easier to write about, does encourage the use of verbs in the past tense, which is not in general as easy to read as present tense.

Maintaining a naturally conversational voice without personalizing content

To write neutral content that enables contributors to maintain a naturally conversational voice without using personal pronouns in the objective case or pronouns in the possessive case, we might consider a set of objective and measurable content guidelines that guides contributors and enables consistency. Those guidelines might include considerations such as:

• The use of neutral and consistent terms and verbs that are verifiable in the domain.
• The diversity of roles in the domain, industries, and locales.
• The activity that a user is performing, the object of work, the subject, and the tools.
• A naturally conversationally tone.
• Alternatives to the use of personal pronouns in the objective case or pronouns in the possessive case.

A few content guidelines to support these considerations might offer wording patterns, term choices, and guidance on grammar and voice. A few examples include:

• Specific wording patterns that incorporate contexts of responsibility and control. For example:
• <Verb, imperative mood> a <name of the document type>
• Maintain a project quotation
• <Verb, imperative mood> a <name of the event>
• Document a sales lead
• <Verb, imperative mood> a <noun> <prepositional phrase>
• Transition a sales event to the next stage in the sales qualification process

[Note: Imperative mood expresses requests or commands, is always in the present tense, and implies the subject you.]

• Domain-specific terms and verbs that incorporate context of responsibility and control with respect to access control permissions. For example:
• Add
• Add a registration to a customer directory
• Assign
• Assign a user role to the person
• Confirm
• Confirm the vendor invoice
• Modify
• Modify the sales agreement
• Settle
• Settle an obligation or an account balance
  
  
• Considerations for content that does not make assumptions about the actions a user can take given that not all users are granted the same access control permissions. For example:
• Noun-based phrases that describe the concept
• The factor applied when converting from the quotation currency unit to the base currency unit
• Considerations for writing content with respect to the diversity of roles in the domain, industries, and the locales that the Microsoft Dynamics AX application supports. For example:
• The term organization applies industry-wide; company applies most specifically to the commercial industry.
  
• Specific wording patterns that incorporate the components of a grammatical structure, accuracy, clarity, simplicity, and a naturally conversational voice and tone for audiences. For example, the sentence structure that applies the pattern <subject> <verb> <object>.
  
  • A journal is a register of original accounting entries.

For more information

For information about content on the user interface, see my earlier blog entry, Content is the user interface.

For information about writing in a naturally conversational voice, see my earlier blog entry, The state of equilibrium: Balancing the voice of the application and the voice of the customer.

We use the term percent to represent a proportional rate expressed in hundredths. For example:

• The organization’s profits increased 1.3 percent this quarter.

A numeral is always used with the term percent in sentences, no matter how small the numeral is. However, in Microsoft Dynamics AX, when the term percent is used in column headings to name the rate percent term in the percentage formula, you will see the term percent without a numeral.

We use the term percentage to represent the rate percent of a base quantity or amount.

The mathematical formula for calculating percentage is: base * rate percent = percentage. The base can be expressed as a quantity or as an amount. For example: 

If you apply a 15 percent discount to a list price of 500.00 USD, the discount percentage is 75.00 USD.

The term percentage is also used when a quantity is not specified, for example, “a large percentage of system resources,” or when applying the percentage formula.

Term challenge

In the sentences that follow, insert the term that accurately completes each sentence.

To see if you applied the terms as we have, click the link in each sentence. Each link will take you to the Microsoft Dynamics AX glossary entry for the highlighted term, which shows you which term we have applied – percent or percentage.

1. A discount is a fixed amount or ____________ deducted from a quoted price or price total.
2. Only 2 ____________ of the test group was unable to complete the task.
3. An ABC classification is a system for ranking discrete categories of items according to Pareto's 80/20 principle that states that a small ____________ of items account for the largest fraction of significance.

But before we examine the concepts named stock and inventory, I offer some background on and a clarification of the term item, which is also applied in unique contexts with respect to the concepts named stock and inventory.

Item

We use the term item as a stand-alone term to name a tangible or intangible object. An item is an element of an itemized list, such as a line item, budget item, stock item, or inventory item.

The following conceptual object model illustrates the term product item. It elaborates the concept named product and the types of products—product item, product service, and product right. The concept named product right was not implemented in Microsoft Dynamics AX 2012.

Microsoft Dynamics AX 2009 does not have a Product information management module, and the term item is used as a stand-alone term in the context of inventory control. A Product information management module was developed for Microsoft Dynamics AX 2012 to maintain data representing products of type item and service. We now distinguish between a product item, a type of product, and an inventory item that is registered as inventory. Although we do use the term item as a stand-alone term when the context is clear, we do not use the term item to mean product item.

Stock, stock item, and stocked

We use the term stock to name a classification of product items that are owned and controlled by organizations. The Microsoft Dynamics AX product is used to document stock flow events, that is, the occurrences of actions that register the inflow and outflow of stock from storage locations. Stock balances are calculated by summing stock flows in and out of storage locations over a given time period.

(Note that in the Microsoft Dynamics AX product, the concept named storage location is named inventory location in the code and warehouse on the user interface.)

In Microsoft Dynamics AX, the term stock is not a synonym for the term inventory because it is necessary for an organization to track quantities of stock that are not used or consumed by product delivery activities, for example, fixed assets, such as chairs and tables.

We use the term stock item to represent an itemized product item that participates in a stock tracking process.

We use the term stocked to represent a policy that controls whether product items are tracked in stock.

The concept named stock was introduced in Microsoft Dynamics AX 2012 so that public sector customers could track product item stock receipts and issues without recording the financial consequences of these stock flow events in inventory accounts. This concept is also necessary for vendor-managed inventory and consignment scenarios in which the organization that controls or possesses stocked items is not the same organization that owns the stocked items.

The concept named stock item has been realized in Microsoft Dynamics AX 2012 by providing an option to set up an inventory item as a stocked product by using an inventory policy.

Inventory and inventory item

We use the term inventory to classify products that an owning organization uses in its product delivery activities and whose value is calculated by using an inventory valuation method and is recorded in inventory accounts.

Microsoft Dynamics AX supports the accounting principle that requires organizations to match expenses to revenue. Merchandising and manufacturing organizations that purchase product for sale or for use in manufacturing activities need to classify costs that are allocated to products as inventory until the products are sold and the cost of goods sold are expensed. Not all stock is inventory, but all inventory product items are stock when inventory is defined in this manner.

Fixed assets could also be a subset of stock, and the value of fixed assets is depreciated over multiple accounting periods.

In Microsoft Dynamics AX 2009, products are set up as inventory items in the Inventory management module. Products of type item and products of type service assume the role of inventory items so that they can be referenced in product structures, such as bills of material (BOMs) and product configurations, and so that they can be referenced when they participate in operating activities (purchase, sales, production, and so on). In Microsoft Dynamics AX 2012, product item and service data is maintained by using the Product information management module. It is still, however, necessary for products of type item and products of type service to assume the role of inventory items and to be set up by using the Inventory management module so that they can be referenced and identified.

A release action is required to release products from the Product information management module for registration as inventory items. A second step is required to set up an inventory item as a stocked item, as an inventory item whose value is classified by using inventory or expense accounts, or as an inventory item that participates as a service in operating activities.

Term challenge

In the sentences that follow, insert the term that accurately completes each sentence.

To see if you applied the terms as we have, click the link in each sentence. Each link will take you to the Microsoft Dynamics AX glossary entry for the highlighted term, which shows you which term we have applied – stock or inventory.

1. The portion of ____________ that is not allocated and which can be used to fulfill new orders and requirements is named available to promise (ATP).
2. An inventory registration policy is a policy that controls when ____________ that is stored in a supermarket is registered as ____________.
3. An expense product is a received product that is a current asset, not held for sale or consumed in production, and for which there is no ____________ control policy requiring quantity tracking or ____________ control policy requiring stock value tracking, and for which there is an accounting policy requiring the recording of the cost as an expense.

These concepts have two aspects: a social aspect and a documentation aspect. In the following conceptual object model, I offer a visualization of these two aspects and of the relationships among these concepts.

Commitment

We apply the term commitment to represent a promise or obligation to perform an activity in the future.

For example, a purchase request documents a requesting organization’s commitment to pay for the product procured for a requisitioner.

This concept is defined in the REA (resource, event, agent) accounting model where it is used to model the formation and execution of commitments between economic units.

Agreement

We apply the term agreement to represent a commitment between two or more parties based on a mutual understanding about their respective rights and obligation.

For example, a purchase agreement documents an agreement between two or more parties based on an understanding that a buying party will commit to purchasing a specific quantity or volume of product over a period of time in exchange for favorable prices and discounts.

Microsoft Dynamics AX 4.0 sales blanket orders and purchase blanket orders have been refactored and reintroduced as sales agreements and purchase agreements in Microsoft Dynamics AX 2012. While the term blanket order is common in the manufacturing industry sector, it is not common in governmental industry sector. Partners can customize Microsoft Dynamics AX so that the terms sales blanket order and purchase blanket order can be used for manufacturing vertical implementations.

Contract

We apply the term contract to represent a legally binding agreement between two or more parties.

For example, a project contract documents the terms, conditions, and status of a legally binding agreement between a buying party and a selling party.

The concept named contract is realized in three unique contexts in Microsoft Dynamics AX:

• As a status documented on a source document, for example, open or canceled purchase order statuses.
• In context of its modular component—project management—and as a social commitment. In this context, we use the term contract to name the legally binding characteristic of a social commitment and the source document, for example, project contract.
• In the vertical layer, partners and customers can implement customizations that support codes of laws that govern contract formation and execution processes specific to a country/region, industry, and vertical market.

Term challenge

In the sentences that follow, insert the term that accurately completes each sentence.

To see if you applied the terms as we have, click the link in each sentence. Each link will take you to the Microsoft Dynamics AX glossary entry for the highlighted term, which shows you which term we have applied – commitment, agreement, or contract.

1. Compensation is direct or indirect monetary and nonmonentary rewards in exchange for services rendered, or an award for damages sustained by an injury or by the violation of a/an ____________.
2. An encumbrance is a/an ____________ made by legal entities to reserve budget funds for expenditure obligations.
3. A trading relationship is relationship that is formed when a buying party and a selling party enter into a/an ____________.

Partners and customers use the Microsoft Dynamics AX application because they need to perform an activity. Their activities may comprise a series of related or unrelated tasks. It is the visual design plus the content design that enables them to navigate through their activities.

Partners and customers rely on the user interface content as one of their primary vehicles for navigating the Microsoft Dynamics AX application in order to perform their activities. In addition, the user interface remains the medium from which downstream product content is developed, for example, help topics. If we do not use precise and accurate terms, verbs, and well-structured phrases and sentences, and ensure that we align them product-wide, and if we do not use a consistent voice and tone in the user interface, then all downstream content types will suffer from the same imprecisions, inaccuracies, poorly constructed text, and misalignments.

(For more information about writing for voice and tone, see my earlier blog entry, The state of equilibrium: Balancing the voice of the application and the voice of the customer.)

The one certain measure of successful activities from users’ perspectives is whether they can complete their activities. In order to rate their activities as successful, we know that they must not encounter any confusing, misleading, imprecise, or inaccurate user interface content—anything at all that causes their work activities to stop and requires them to switch work contexts to question or research the text that they see on the user interface in order to determine their next step.

Deciding what content to add to the user interface can be a daunting task. Questions that often arise during this work include:

• Which terms and verbs do I select from my conceptual object models for the user interface?
• How do I know which other terms, verbs, phrases, or sentences to add to the user interface?
• If I am reviewing a specification, how do I evaluate whether the proposed terms, verbs, phrases, or sentences are precise and accurate with respect to the domain?
• I know what content I need to include on user interface, but how do I phrase it to ensure consistency in wording product-wide?
• How do I choose and ensure consistency in voice and tone?
• How do I document the steps to perform an activity through user interface content?

Given the importance of content design for the user interface, I maintain alignment with the Metro design language principle and with respect to a user’s work context that content is the user interface.

Content design considerations

Product development comprises many aspects. For the communication aspect, there are two designs that are inextricably linked—visual design and content design. A successful product cannot embrace a visual design or a content design that is not aligned with the real world.

When content is the user interface and when words are the icons, or at the very least complements of the icons that appear in the application, then visual design must also include content design. And the content that appears in the product should:

• Be designed to support the architecture of the product.
• Align with the product design.
• Align with domain concepts.
• Align with industry, domain, role, and locale.
• Align with user work context.
• Align with user interface control modalities.
• Be designed for partner customization and extension.

To write user interface content that aligns to these considerations, the contributor must have depth and breadth of knowledge of the domain and of end-to-end scenarios, case studies, and solutions by industry, role, activity, and work context. It should be the goal of user interface content to align with the product architecture and design; domain; and the activities that a user performs in the application.

Guidelines and wording patterns

While there is no substitute for depth and breadth of domain knowledge and product knowledge, guidelines and wording patterns can often help inform the terms, voice, and wording patterns that enable alignment with visual design, and product-wide, and with the industry, domain, role, and locale.

A few key considerations for guidelines and wording patterns for user interface content might include:

• Select industry-neutral terms so that the terms can be aligned across all industries, such as legal, financial, healthcare, education, public services, government, and so on.

For example, the term prospect is neutral and can be applied industry-wide in contexts such as these:

• A participant that has the existing and potential ability to provide a service or probable future economic benefit to a legal entity. 
  (domain, product-wide)
• A potential customer. 
  (domain, service industries)
• A potential client. 
  (domain, service industries, such as law firms)

• Select terms that map to concepts that are verifiable in the domain because these terms align generally across domains, such as commercial, public, not-for-profit, and so on.

For example, the term data object applies domain-wide; business object applies most specifically to the commercial domain.

• Add content that does not make assumptions about the actions users can take. After all, not all user roles are granted the same permissions.

For example, the help text for the label Project contract might read Add a project contract. However, if the user does not know what a project contract is, or if the user does not have permissions to add a project contract, then how does this text help the user understand what the concept named project contract is and whether this concept applies to his activity? It might be more enabling and useful to document what the concept is, rather than describe what to do with a field. A recast of the help text might read The project contract documents a legally binding agreement between parties. Given the allowable actions that appear based on the permissions that have been granted to the user, this text would likely offer enough information to inform the average user’s next step.

• Select terms and write phrases that consider a worldwide audience even if the content is translated. Follow established grammar, syntax, and punctuation rules. And use a voice and tone that embrace a formal, clear, simple sentence structure (subject-verb-object) and a naturally conversational tone.

For example, an error message might read Not Authorized to insert a Record in Table “SYSACTIVETEMPTABLE”. This message describes the problem from the perspective of and in the voice of the application, uses random capitalization, and does not offer a solution to the problem. A recast of this error message might read You are not authorized to add a new active employee to the system. Contact the security administrator to resolve this problem.

• Reject presumptions of “customer advocacy” to drive choices of guidelines, terms, and wording patterns. Every person that is asked for his take on a point in context of customer advocacy will have a different opinion based on his interpretation of the customer. Objective guidelines that are designed to ensure measurability, consistency, precision, and accuracy are not the best medium in which to capture and document peoples’ opinions. Do make sure that every guideline or wording pattern that is authored is objective and can be supported by specific data points, not opinions.

For example, while the term quote is recognized in the United States as a synonym for quotation in the context of request for quotation, the term quote is not used in most other languages to represent a synonym for the term quotation.

In the following table, I offer a few examples of proposed content, identify the issues that objective writing guidelines and wording patterns could solve and measure, and I offer updated versions of the proposed content based on guidelines and wording patterns aligned with the preceding considerations.

Microsoft Dynamics AX glossary

I invite you to peruse the Microsoft Dynamics AX glossary to see examples of how guidelines and wording patterns have enabled consistency, clarity, precision, accuracy, voice, and tone in context of product content that we deliver in the glossary and some of which we deliver on the user interface. And I invite you to offer your observations on our glossary content.

• 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 13^th 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.

While the focus of this blog entry is on glossary entry submissions, the practice I document is applicable to all product content that we deliver, such as user interface strings, help topics, and so on.

What is quality?

Quality can be defined for many contexts. For example, quality can be defined in context of a distinguishing characteristic, a perception, or with respect to a condition.

If I asked you what quality means to you, you might offer a response based on your perceptions of quality, or based on your experience with an item’s condition or its characteristics. Your response might evolve as a result of how much or how little you value the item. And your perception of quality would likely include a consideration of the weight of the value of quality against the specific item that you are evaluating and how important that item is to you or to your organization.

For example, if you and I were to evaluate the same chair for purchase, our perceptions of quality might differ with respect to the condition of workmanship or its upholstery.

So would a difference in our conclusions make either your or my evaluation of quality more or less valid in this example? No, it would not.

What this example indicates, though, is that the concept named quality can be classified as either subjective or objective. With respect to our terminology practices, we developed a practice of evaluating quality that is objective.

Our need for a practice for evaluating terminology quality objectively was borne out of:

• The need to move people away from using terms that existed in other applications that they had developed or used, many of which contain terms that are not verifiable in their respective domains.
• The need to align the diversity of roles in the domain, industries, locales, and so on that the Microsoft Dynamics AX product supports.
• The need to align with the Microsoft Dynamics AX product design. We build a platform that our partners tailor, so the concepts and their names need to remain neutral and consistent with concepts and their terms that are verifiable in the domain.

How do we measure the characteristics of quality?

The concept quality cannot stand alone as the criterion for an objective evaluation. The concept quality requires a measurement to ensure that the evaluation can be calibrated objectively and that the conclusion of the evaluation is repeatable, no matter who the reviewers might be.

When measured, quality is measured against a normative system of measurement, and any variations to this measurement result in nonconformance.

Normative systems of measurement can be units of measure that produce an exact measure of some countable operational or financial characteristic, and it is represented by a number. For example, systems of measurement that are applied to software design might include measurements of technical requirements, test requirements, conformance requirements, performance requirements, audit requirements, and so on.

The specific system of measurement that we apply to the evaluation of product content is conformance to sets of writing guidelines. Product content, including glossary entries, user interface strings, help topics, and so on, should read as though it was written by one team and not by many team members.

When objective guidelines are documented and accepted, such as rules of grammar and syntax, product content, such as proposed glossary entries, can be evaluated against established guidelines and objective feedback can be offered that documents conformance or nonconformance to guidelines. An example of an objective measure with respect to definition authoring might be: Does the definition follow prescribed grammar and syntax guidelines?

The Microsoft Dynamics AX terminology practice requires that:

• Concept definitions and term selections be accurate and precise and verifiable in the real-world domain. For example, the language and terms that appear in the Microsoft Dynamics AX product should align with the established language and terms that people learn when they study a domain and in which they get certified in order to perform a certain role.
• The concept must be realized, implemented, and aligned product-wide. For example, the concepts named vendor and supplier are unique and are not synonymous, so the Microsoft Dynamics AX product should reflect the concept that has been realized and implemented in the product—that is, the concept named vendor.
• Definitions must follow established grammar and syntax rules. For example, definitions must apply correct capitalization and punctuation rules.
• Specific definition wording patterns must be applied based on the part of speech of the term. For example, definitions for nouns must start with an article (a, an, the).
• Specific definition wording patterns must be applied when defining concepts that are of the same type. For example, the definitions for documents, such as customer invoice, request for quotation, and sales order should start with the phrase A source document that documents.

We established wording patterns to align to the practice of software design, which applies patterns. And we established wording patterns because of the number of repeatable activities in our domain. We have numerous documents, such as source documents and business documents. Because they all document something, we established a wording pattern to maintain consistency in the wording for definitions that document the same concept type.

When a proposed glossary entry is submitted for consideration as an entry for inclusion in the Microsoft Dynamics AX glossary, I measure the proposed glossary entry against these and other established objective guidelines, and at the end of my review, I assign an objective mark—Approved or Denied—to the proposed glossary entry.

The key to my remaining objective is to ensure that the guidelines I authored are objective so that the evaluation questions that I pose can conclude with an objective, binary response: yes or no; 0 or 1. I need to be able to enumerate the evaluation questions and then count the number of yes responses and no responses, thereby determining a numeric result, such as yes=6; no=0; or yes=2; no=3. This numeric result would inform next steps for me (the terminology manager) or for the submission contributor.

The sum of the parts: Examples of how we measure the characteristics of quality

When a glossary entry is proposed for inclusion in the Microsoft Dynamics AX glossary, the accuracy, precision, and quality of it is verified and validated against established guidelines. The result of the evaluation determines the quality of the submission objectively—that is—with respect to conformance to established guidance. This result determines whether the entry is eligible for inclusion in the Microsoft Dynamics AX glossary or if the entry requires modification.

I offer two groups of glossary entries below that document types of concepts in Microsoft Dynamics AX, and for the purpose of example, I evaluate the quality of these contributions against only these two guidelines:

• Specific definition wording patterns must be applied based on the part of speech of the term.
• Specific definition wording patterns must be applied when defining concepts of the same type.

The specific questions that a reviewer might ask in evaluating the quality of glossary entry submissions with respect to these two guidelines might be:

• Does the definition apply the established wording pattern based on its part of speech? [Noun entries should start with an article.] Yes/No
• Does the definition apply the established wording pattern if a wording pattern exists for the concept type? Yes/No

Source document concepts

In the following proposed glossary entry submissions, I underline instances where the guidelines have been met as prescribed.

• product receipt (noun) – A source document that documents the receipt of products ordered, the receipt of products returned, or the receipt of products received on consignment.
• purchase agreement (noun) – A source document that documents the offer to buy products or the acceptance of an offer to sell products in exchange for payment.
• purchase order (noun) – A source document that documents the offer to buy products or the acceptance of an offer to sell products in exchange for payment.

Rule concepts

In the following proposed glossary entry submissions, I underlined instances where the guidelines have been met as prescribed.

• rule (noun) – A condition-action pair that prescribes the action taken when the condition is met.
• accounting rule (noun) – A rule in an accounting system that controls the principles, methods, and procedures for classifying, recording, and reporting the financial consequences of business events.
• recognition accounting rule (noun) – An accounting rule that prescribes the recognition of revenue and expenditure in accounts and on financial statements.
• revenue recognition accounting rule (noun) – A recognition accounting rule that prescribes the recognition of revenue in accounts and on financial statements.
• expenditure recognition accounting rule (noun) – A recognition accounting rule that prescribes the recognition of expenditure in accounts and on financial statements.

Both sets of examples offer proposed glossary entry submissions that meet the two objective guidelines (as well as others that are not noted here). As a result, these proposed entries were approved for inclusion in the Microsoft Dynamics AX glossary.

Microsoft Dynamics AX glossary

I invite you to peruse the Microsoft Dynamics AX glossary to see examples of other types of entries that met our terminology quality acceptance bar. And I welcome any feedback that you have to offer.

For those of you for whom sentence diagramming is a distant memory, let me kindly offer a refresher—diagramming sentences is the practice of visually representing the grammatical structure of a sentence by differentiating the parts of a sentence that comprise a thought or a concept. The goal of this practice is to promote the logical rules of syntax and word structures.

How the practice of diagramming sentences aligns with the practice of defining concepts

Early in our development cycle, we noted a lack of writing patterns with respect to the sentence structures for defining concepts. We discovered that random combinations of phrases emerged, many of which did not follow established good writing practices.

We discovered that when stakeholders were not able to describe concepts with respect to their domains or to name them, their practice was to write complex sentences that describe the purpose of concepts or the usage of concepts. This practice has proven prone to misalignments and inconsistencies in phrasing and inaccuracies in intended meanings. Feedback from our translation teams also confirmed that these misalignments, inconsistencies, and inaccuracies in applying the logical rules of syntax and word structures have affected the clarity and accuracy of translated text.

To address this challenge for stakeholders and for translators, we developed a terminology practice in which stakeholders elaborate conceptual object models that define and describe object structure and behavior in the real world. (For more information about elaborating models, see my earlier blog entry The origin of Microsoft Dynamics AX glossary entries).

To write the guidelines for definition authoring, we evaluated the components of a sentence and their relation to each other. Then we developed guidelines for defining concepts that follow the logical rules of syntax and word structure and for establishing sentence patterns.

The output of applying the guidelines during the development cycle has produced consistency in sentence patterns that are written to define concepts. We also learned that the consistency in sentence patterns has enabled consistency and precision in translation.

While the application of the practice of diagramming sentences has informed guidelines for our terminology process, this certainly does not mean that my colleagues and I spend our days diagramming sentences or memorizing the parts of speech and the rules of grammar and syntax. What it does mean is that the guidelines that we offer for defining concepts are rooted in established fundamental writing practices that include the logical rules of grammar, syntax, and word structures.

Testing the guidelines

To determine whether the guidelines would yield consistency and accuracy in concept definitions, we put our guidelines to a test. We diagrammed the sentences that were authored by following the guidelines that we wrote. Then we evaluated whether the definition was interpreted accurately with respect to the concept in the domain as defined in its respective conceptual object model. Where there were differences among the conceptual object model or the written definition and its corresponding sentence diagram, we learned that we needed to add or modify guidelines, particularly with respect to writing complex or compound definitions.

Aligning concepts and diagrams

I offer an example of Microsoft Dynamics AX source document concepts and their diagrams below. In the following term entries, you can see sentence patterns that are used consistently.

• production order – A source document that documents the requirements for producing items to meet a demand.
• purchase order – A source document that documents the offer to buy products or the acceptance of an offer to sell products in exchange for payment.
• sales order – A source document that documents the offer to sell products or the acceptance of an offer to buy products in exchange for payment.

In the diagrams below that correspond to these defined concepts, you can see how the components parts of each sentence align to the component parts in the other sentences and how they validate the real-world concepts as they are defined with respect to the domain and their respective conceptual object models.

production order

purchase order

sales order

Just for fun . . .

Can you read the definitions offered in the following diagrammed sentences?

To see whether your reading matches the definition we documented, click the linked term to go to its term entry in the Microsoft Dynamics AX glossary.

conform

currency

journal

schedule

void