Content is the user interface

In Microsoft Dynamics AX, product content comprises all of the text—the terms, verbs, phrases, sentences, and so on—that appear on the user interface (UI), in tooltips, in error messages, in the glossary, and subsequently, in help topics, in white papers, and so on.

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.

Proposed content example	Issue with example	Updated example
The value <abc> in field 'Country/region' is not found in relating table 'Country/region'.	This error message describes the problem from the perspective of and voice of the application. It does not align terms precisely or accurately with respect to the domain. It does not offer a solution to the problem.	The location that you entered was not found in the reference list of countries and regions. Add the location to the address setup, or select one of the reference country/regions.
goods and services products and services	These phrases do not align with the names of the concepts that are realized and implemented in the application.	items and services product (Product is the term that we use to name the combined concepts item, services, and rights that are realized and implemented in the application.)
deliver remaining under delivery assessment principle	These terms are not verifiable with respect to their concepts in the domain.	outstanding quantity quality tolerance recognition accounting rule
Post packing slip Post invoice	These phrases use imprecise or accurate terms, and the actions they document are not verifiable in the domain with respect to their concepts.	Confirm product receipt Confirm vendor invoice
Do you want to pre encumber purchase requisitions? Yes will pre encumber and if budget check and recording in ledger are successful, purchase requisition will no longer appear in the unposted purchase requisition list. No will close the form and the error icon still appears in the list.	This message describes the situation from the perspective of and voice of the application. It does not align concepts or terms or verbs with the domain accurately or precisely.	Do you want to pre-encumber budget funds for this purchase requisition? Budget funds must be pre-encumbered before a purchase requisition can be opened to the sourcing process.

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.