SeSAM has gained a level of interest lately (www.sesam-info.net). The controversial part of SeSAM is that an information analysis, to determine what content to write in end user documentation for a technical product, is not starting with an analysis of users, their goals and tasks, but the Meaningful Result Statements (MRS). Don’t get me wrong here; knowledge about users are a fundamental part of SeSAM, but they are not the first thing you focus on. Most of the content you need to write is derived from the MRSs. So what is a meaningful result statement? Read this blog post to find out.

The purpose of a technical product is to help the user accomplish something; to help the user solve a problem, a need or a requirement. The user is buying the product to solve the problem, need or requirement and wants to do it as easy, fast, secure and convenient as possible. The primary focus for end user documentation is to help the user use the product to solve these problems, needs or requirements.

The possibilities the product offers to solve the problems, needs or requirements can be modeled as meaningful result statements (MRS). The MRSs mirrors the results the product offers that are meaningful to the user. Be aware! A MRS is not the same thing as a product feature, function, software/hardware component.

The following fictitious situation can help you understand what a MRS is. Let’s say you are a technical communicator, in need of finding the MRSs for a new mail software “ABC” that your are documenting.

A person, who is a newbe to mail software in general, is planning to purchase/install or has started to use the new mail software ABC in a particular context, for example an office environment. Let’s call this person “the user”. Then another person, who is an experienced expert in using the new software ABC, is located some desks away from the user. Let’s call this person “the expert”. The user is asking the expert “I’m trying to understand what this software can help me do. I’m not sure it can do what I want. What can this mail software do that is meaningful to me?”. The expert says

"You can use the mail software ABC to:"

• Read mail that someone has sent to you.
• Write and send a mail to someone.
• Register, keep track and view contact information about the people you send and receive mail to/from.
• Store and keep track of meetings and appointments in an electronic calendar.

The expert is showing the user around in the software, either as seen on for example the computer screen or by showing something, like a print out. “And” the expert says, “after you have received and read a mail from someone, you can:"

• Forward the mail to someone else.
• Answer the mail (reply).
• Move the mail to a preferred location within your mail box.
• Move the mail to an archive location, which means that it is deleted from your mail box since it has a limited amount of space.
• Print the mail.
• Export the mail as s document file.
• Delete the mail.

Then the user says: “OK this is as I thought, but is it possible to customize the way you read or send mail, because I want to do xyz”. The expert says “Regarding receiving mails, you can select, define or choose:"

• In which folder incoming mails are automatically stored based on recognition of certain text strings in subject or body.
• How mails are sorted in a particular folder (by date, by size etc).
• If the mail text shall be shown in a large or small font.

“And regarding writing and sending mails, you can select, define or choose:”·        

• What type of information to include in a mail to send (textual information, meeting invitation etc).
• How the text in a mail is formatted.
• If a mail shall include objects such as documents, images, video or audio.
• If a mail shall include links to other sources (web pages, data base sources etc).
• Who to send a mail to (one/many/using a distribution list).
• If a mail is saved or deleted once sent.
• Where, in which folder, to save a mail you have sent.
• How important a mail is (private, urgent etc).

“And” says the expert, “the mail software can also support you while you are reading or sending a mail. It can:”

• Issue an acoustic alarm when mail box has reached 90% of its size. You can also customize how loud the alarm shall be and how often it is given.
• Show a pop up window to indicate that you have received a mail (when you are not actively working in the mail software).
• Show a pop up window to confirm that the mail has been sent.
• Show a pop up window to confirm that your mail has successfully reached the recipient mail server.
• Show a pop up window to alert if the mail could not be sent (maybe you have typed the wrong address or the mail server could not be reached).
• Show a pop up window to confirm if and when the recipient opens the mail.

The user, in our fictitious situation above, is actually located in search situation 1 and the answers that the expert is giving are the information that is needed in search situation 1 according to SeSAM.  A SeSAM manual shall provide the answers given by the expert, but written to target the assumed user. The expert says “Check out the manual and section 1 where you can find information about what I just talked about”.

So what is a meaningful result statement for our mail software ABC in this fictitious situation? Let’s examine the basic components of a MRS first:

Figure 1: Basic components of a Meaningful Result Statement (MRS)

A MRS must have a trigger. A trigger activates the product to generate the meaningful result. To “generate” means that the product is, for example, executing a code snippet. The user or an external conditions can be the trigger. When the user is the trigger, the user must perform a task which is captured in a DITA task topic. External conditions are for example when the outside temperature falls below a certain level. The result is a meaningful outcome that is “visible” (possible to see, hear, feel or measure etc) in the user interface.

It is often possible for user to customize various aspect of the MRS; what or who is trigging, how the result is generated (different activities), the appearance of the result (size, shape, where it show up in product interface etc). The customization possibilities allow the user to adapt the product to the needs in a particular operating environment.

There are different types of MRS. There are pre MRS, post MRS and supporting MRS. They all form what is called the main MRS. 

Figure 2: Components of a main MRS

So what is a main MRS (the red circle in figure 2)? The first statements the expert made in our fictitious situation are the main MRS:

• Receive and view a mail (the result is a window on screen, showing the mail).
• Write and send mail (the result is that another person has your mail in its inbox).
• View a registered contact (the result is that information about someone you want to send or receive mail to/from is stored and retrievable in the software).
• View a registered meeting in the calendar (the result is that a meeting occurrence is registered and viewable in the calendar).

Each of these MRSs are meaningful for the user, even if only one of them would be present in the product. The main MRSs are the reason to why the user is buying the product.

So what is a pre MRS? To be able to deliver the main result, a series of sub results must be completed. Each of the sub results are only meaningful in the context of the main MRS. The pre MRS for the main MRS “Receive and view a mail” are for example “mail is received and stored on mail server”, “mail is visible in inbox folder” and “mail is visible in a mail window”. This means that some main MRSs involves the user to craft the result, as when office software is used to create a document. For some other main MRSs the user is not involved at all, as when an acoustic alarm goes off when the outside temperature is below a set level.

The pre MRS are mainly used to understand how the main result is generated, thus most often the pre MRS do not need to be described in detail in end user documentation except the user task to trig and the customization possibilities. As for any type of MRS, each pre MRS has a trigger (the user or external condition), the product is doing something and there is a visible result. Each pre MRS can be customized, in our fictitious situation the user can select to which folder an incoming mail shall be stored, how mails in a folder shall be sorted etc.

So what is a post MRS? Once a main result is available, the user can do various things with it, for example deleting it, moving it, printing it etc. In our fictitious situation the user can delete a mail, forward a mail, reply to a mail etc. A post MRS can of course be customized.

Finally, what is a supporting MRS? Often, a technical product has supporting possibilities that helps the user manage the results, stipulated by the main MRS, successfully. A supporting MRS is for example an indication in the user interface that a pre or post MRS has started, is in progress, is completed, was not possible to complete, indication of what went wrong when the pre or post MRS could not be completed etc. The result from a supporting MRS is visible via icons, dialogs, prompts, flashing LEDs etc in user interface. The supporting MRSs are only meaningful in the context of the main MRS. Furthermore, the trigger of supporting MRS can only be the product itself, meaning that the user can never be the trigger of a supporting MRS. And, a supporting MRS can also be customized. Some (complex) supporting MRS are built on an own set of pre MRS that in turn can have supporting MRS.

The information needed in search situation 1 involves the MRSs. The MRSs can then be described from various perspectives such as who the intended receiver of the result is, what the purpose of the result is, what is trigging the product to deliver the result, how the result is generated, where the result is visible in user interface, with what performance the result is delivered, what limitations exists, how the MRS can be customized etc. The amount of details to include depends on the domain knowledge that the user is assumed to possess.

The user tasks for search situation 2, 3, 4, 5, 6 and 7 are derived from the MRS. Check out the next blog post for the continuation of the office drama.