Disruptive Innovation: Documenting SDL Experience Manager and Smart Target Specifications

The idea of "regions" are important to:

Experience Manager (XPM), SDL Tridion's in-context editing interface, where XPM regions allow content placement
Smart Target, the connection between SDL Tridion and Fredhopper, where ST regions show certain content based on things like search terms or visitor or session-based triggers (and show fallback content when nothing triggers)
Content Management System (CMS) Functional Designs for (SDL Tridion), where "regions" identify where content types are allowed and in what quantities

Although technical users or developers will implement these pieces, XPM and ST requirements are business-driven. Here as some example formats I've been using on recent projects. Although I hint at some of the process, this isn't a comprehensive guide as there is more that you'll want to consider in a SmartTarget or Experience Manager setup!

As an overview, consider the following details in your next Functional Design:

XPM Regions -- as a table identifying the regions for a given page type
XPM Page Type -- a specific instance of a recommended XPM page type
XPM Custom Content Type -- selectable, pre-configured or prototyped content options in XPM
ST Triggers and Footprints -- the set of known and implicit visitor/session-based triggers for targeting and the ways to test those in the CMS
ST Regions -- where promotions should appear in the site, across page types

Experience Manager

XPM Region Specification Example

Here's an example of a specification for XPM regions, which directly translate to the XPM format code template developers will need to set up. Create a set of regions for a given website or shared "design."

Region Name	Min	Max	Allowed Component Presentations (Schema + Component Template)
Banner Main	1	3	Image + Image Banner Video + Video Carousel etc.
Main Content	1	--	Article + Article [Main] Product + Detail [Main] Solution + Detail [Main]

Visually you could mark these on the design wireframes or add a diagram like the following:

In terms of implementing regions, consider the configurable XPM Region option Nuno Linhares shared or see the Tridion Reference Implementation for a way to automatically create MVC view-driven XPM regions (login required).

XPM Page Type Specification Example

After detailing regions, you will want to document Page Types. Though Page Types straddle the realm between users, the business, and CMS administrator, documenting these up front can complete the end-to-end content model where you:

Start with Information Architecture activities and designs for User Experience and User Interface
Confirm page types, content types, and regions.
Then after designing Tridion Schemas, Component Templates, and Page Templates, you revisit example and "prototyped" (to be copied) content and create the page types and content types you started with.

At the minimum, you need a working Tridion page to create a Page Type. Set the "[x] Use this Page as a Page Type" check box and in the Component Presentation tab, set each Component Presentation.

In terms of functional requirements, we need the following:

Schema
Component
Component Template
Copy or Include setting
The corresponding prototyped content (that will be copied or included/referenced)

You could create a table like this.

Region / Allowed CPs / Qty	Schema	Component	Component Template	Copy or Include	Example and Note
Banner Main	Image	Some Image	Image Banner	Include	CMS user can change banner if they prefer
Main Content	Article	Some Main Article	Article [Body]	Copy	Create a "Lorem Ipsum" article prototype -- this could store Web page metadata as well

You don't necessarily need a diagram for the page type, but visually you might use icons or more boxes to explain the above table.

If already set up, you could take a screenshot of the configured page type in XPM.

XPM Custom Content Type Details

A configured Content Type has similar requirements:

Name (Content Type Title)
Content Type Description
Content Title (user or auto generated)
Naming convention (allowed placeholders for auto generated):

%N% for Name of original component
%P% for Page created
%U% for User
%ID% for Component ID
%D% for Date (time stamp)

Prototype Component
Folder (Storage Location)
Component Template
Insert position (Top or Bottom)

This is a bit much for a single table for all Content Types--one table per Content Type would work better in documentation. Pictures from the wireframes or creative can also help.

Borrowing from the Tridion Reference Implementation, you might add screenshots for something like a teaser.

But I would recommend setting up XPM first, have CMS users create prototype Components, and then confirm how these will evolve. With so many variables, I think interviews and iterative Content Modeling is the best fit for these (and as such, CMS consultants might not be the ones defining these).

SmartTarget

SmartTarget 2014 lets users configure promotions from the integrated Slide Out Navigation by choosing which list of promotions (Staging for testing vs Live for production), which publication, and visitor or session-related triggers will cause a visitor to get a given promotion.

SmartTarget regions have a different purpose that XPM Regions, but you might consider a way to consolidate or create a switch between CPs in an XPM region and fallback CPs in a SmartTarget region.

SmartTarget Triggers and XPM Footprints

In terms of triggers, you want to identify two parts:

The desired default and custom triggers for promotions, based on business requirements and known data for the client's personas. This will be available in the SmartTarget promotion settings.
Custom Footprints for testing by CMS users in XPM (on the Staging site)

In this following example, my client had existing and new segmentation and geo-targeting attributes it wanted to target. To be able to tag content for these as well, I documented the options for the Content Manager-side in the Categories and Keywords.

Though you can create Custom Triggers and skip Custom Footprints, you really want to offer CMS users a way to test the contextual scenarios. Since the Footprint options should match the visitor segment scenarios, you can create a single table to define both of these:

Custom Trigger Types, which might be text, date, Boolean, number, with a multi-value option
Custom Footprint Types, which may present as radio, drop-down/select box, date, with the ability to restrict options by regular expressions

Though specific to SDL software, these are still related to functional specifications. Technically, the Footprint acts against Ambient Data Framework (ADF) keys, but the functional task here is to confirm the personalization scenarios CMS users need to manage as well as test. The actual implementation may adjust these as needed (not all "personalization" will end up being SmartTarget).

Update (2015/06/10): to be clear, the triggers and footprints are independent of Content Manager Categories. I sometimes re-use a list defined in my documentation, but this isn't integrated (but would be a nice feature).

Name	Purpose	Trigger	Footprint
Visitor Authentication	Allow ST ability to trigger on Visitor authentication. Allow XPM user to preview site based on authentication status, without logging in	text ~~use values described in Categories: Visitor Authentication~~	Text or separate Boolean options
Visitor Segment	Allow ST ability to trigger on Visitor Segment. This will be used in promotions. Allow XPM user to test visitor targeting without logging in to a test account	text ~~use values described in Categories: Visitor Segment~~	Text or separate Boolean options
Visitor Geo Market	Allow ST ability to trigger on Visitor location. Allow XPM user to test geo-market targeting from the safety of their desktops or laptops	text ~~use values described in Categories: Visitor Geo Market~~	Text or separate Boolean options Optionally use a regular expression to limit values to IP addresses

If using SDL Tridion's Audience Manager, consider defining some custom personas for testing as well.

In order to promote content with ST, we need regions in addition to the triggers.

SmartTarget Region Example

Like XPM regions, ST regions have names and limits (but no minimum). You could document ST regions in a table as well.

Region Name	Max Items	Fallback Content (Component Presentations)	Template details
Banner Main	3	Fallback Image + Image Banner	Add details such as (translatable) "label" text or additional content (CP) that should show in the region
Main Content	1	Fallback Article + Article [Main]

Finally, with SmartTarget Regions and Triggers set up, CMS users will create the actual ST promotions.

SmartTarget Promotions (ST 2014)

ST Promotions need to define the following attributes:

Name
Publications for display
Include Child Publications (Y/N)
Available Page Regions
Triggers
Content
(Folder, Keywords, selected Components) and Attributes

But at this point, you're at the level of managing the promotions. You may want to suggest some examples or get typical use cases, but CMS users business or Marketing users will create and manage the promotions using the regions, triggers, and custom footprint you've defined.

Welcome to the new modeling!

Quick Schema Update

Bonus: I forgot Schemas. Today's specifications need two more fields for:

Inline Editing (XPM-enabled)
Translatable (for managed translation)

To keep it clean, I'm opting for "X" instead of Yes/No everywhere (like how I prefer feature-based CMS designs).

Description

XML Name

Field Type

Mandatory

Inline Editing

Translatable

Height

Multivalue

Rich text

Properties / comments

But if you're serious about agile" CMS development, consider prototyping and creating the Schemas jointly between developers and the CMS authors.

And for more ST information see:

Recent SmartTarget questions
Jan Horsman has a few ST posts and code
Robert Curlette has a few podcasts on previous ST versions
Overviews
How I'm doing content models more recently (CPs on a page aren't new)

Navigation

Documenting SDL Experience Manager and Smart Target Specifications