Documenting Component Presentations

This question came up today in a functional workshop:

"When and how do we document Component Presentations?"

A component presentation is the combination of a specific component and template. It becomes the rendered output to whatever digital channel you're managing. The basic, intuitive answer might be that we do not document these directly. We define the content management system and it's up to content authors to put in the "real" content. It's all structured and templated so we don't care, right?

Typically we define and confirm a few CMS elements:

• Page Types
• Content Types*
• Schemas
• Component and Page Templates

We define or specify individual components mainly through their schemas, which determine component fields and options. What about component presentations?

*Content Types as an information architectural concept roughly equate to component presentations in SDL Tridion, though you could argue they're actually equivalent to schemas (as types of components, yeah?).

But we define and specify certain "component presentations" in these scenarios (or at least parts of them):

• Global Items. For any globally-managed content or Tridion-managed settings
• Good Defaults and Known Variations. When there should be pre-selected options (maybe Keywords) to choose from even when the fields are "wide open."
• For Inline Editing. In Experience Manager Content Types are based on actual content--you need a filled-out component to set a content type.

The values in my Loerm Ipsum example are not defaults nor are they templated, the values are prototyped.

Sometimes we want to know the specific variations and not just Lorem Ipsum content. Most likely you'll see this in:

• The company logo, header/footer links, and other navigational items.
• Standards and content preferences in style guides. The company name must be spelled a certain way, even if authors must type it in manually.

"Wide open" fields could control everything from colors, to pop-ups, limits on returned items (e.g. number of related articles). You might simplify these in a few ways:

1. Set a default, especially when it's known in advance or is usually a certain value.
2. Create a prototype (especially with Experience Manager content types). Although authors could change the value, there might be two or three basic options that authors would want to choose from.
3. Add instructions in the field description or in a custom url.

Good defaults and prototypes help address scenarios when CMS developers introduce near-infinite "template" or design choices. This happens almost any time you have: 

• fields called X, Y, height, or width
• drop-downs for colors
• checkboxes or options that depend on the channel
• a selection for "renderer" or "view" in a component

Before you cry "un-mangeable" and breaking "best practices," this is a common scenario in retail and promotional situations that want to balance design with accessible text. The promo can't simply be a clickable image and though content is structurally the same, fields and values must be placed in specific regions, with specific colors, possibly with a very specific design, all controlled by the content author.

So this won't work when "X" and "Y" could be anything:

Instead you have the ability to prototype this setup (image on the left) or put values in another component that acts as a component presentation (image on the right):

See this Tridion Stack Exchange question for where I first described these approaches. The ideal way to use prototypes with Tridion is simply copy & paste in the Content Manager Explorer (optionally using some type of extension or even system to help automate this) or through Tridion Content Types in Experience Manager.

So it's not just schemas and templates. Though the rest of the content will be managed by content authors, your functional CMS design work will include actual content and examples. We have global items that we'll define in the FD along with some good prototyped defaults.

You can place this information in the content types section and reference it in schemas or templates as needed. Ultimate flexibility has a not-quite ultimate cost on content authors, when you have good defaults and known variations, prototype the differences.