The duality of objects of work—Distinguishing objects of work that live outside of an application from those that live inside of an application

Microsoft Dynamics AX product content comprises the terms, verbs, phrases, and sentences that appear on the user interface (UI), in tooltips, in exception messages, in the glossary, and subsequently, in help topics, and in white papers. In our product content, we should follow a practice of distinguishing objects of work that live outside of the application from objects of work that live inside of the application.

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.