I'm back from a Partner Bootcamp, where I created the following ice-breaking exercise to help Sites and Docs practitioners understand how their respective content models compare. For more about boot camps read my last post. Otherwise, read on to see how you might adapt this exercise for your next presentation.

Step 1: Volunteer or Voluntold

First I asked two volunteers to kindly come up to draw and answer a few questions. These can be anyone familiar with at least the main concepts in Sites and Docs.

Step 2: Definitions

I then had them start with the basics with these questions:

• What is the basic content-containing element in the software?
• What is it stored as?
• What defines its definition?

Both Sites and Docs store modular pieces of content as XML, however, Docs leverages the DITA OASIS standard to offer a bit more "in-content" structure such as embedded and conditional content as well as references.

Step 3: Content Types

We then compared common types of content between the systems with these prompts: 

• Based on these definitions, what are the basic types of content you see in implementations (e.g. article or topic)? Write some examples.
• Do you see any bad practices or types that shouldn't be used by customers?

For example, a Docs setup might have topic types such as Task, Concept, or Reference, whereas Sites might have schemas such as Article, Blog, Carousel, Link List, and so forth.

I joked about some infamous schema and item names such as "Article 2," "Article-do-not-use," and "Home Page (Old) Old."

Step 4: "Pages" and Outputs

We then drew how content comes together and how the source content is transformed into an output.

We ended up with logos, topics, banners, and lists across the two drawings.

Both Sites and Docs can render content into nearly any machine-readable format imaginable. Though their content storage attempt to both be semantic and agnostic of the rendering, Sites does offer a selection for editors to choose a different "template" to change the layout and/or rendering of content.

Step 4: Variations

This is where the difference between Sites and Docs becomes apparent and was the conclusion for my quick-and-dirty on-the-spot ice-breaking exercise.

Though we didn't actually draw Publications, BluePrints, or Baselines this last part explored and discussed how both Sites and Docs handle variations of the same or related content in really unique, powerful, yet complementary ways.

Variations Within a Sites Publication

Within Sites, the delivery side is relatively agnostic or unaware of the history of any piece of content. The delivery site shows the "latest-and-greatest" published version of an item. However, BluePrinting enables the combination of shared, global content with local control or localizations of variations.

The BluePrint is set up for editors and editors have the choice to tweak and adjust (localize) content in the given context of their Publication. And any given Publication may have a mix of shared and localized content based on the use case, which might be source content translated into a specific target and/or content localized for a given market or even channel, device, or customer segment.

Variations Across Docs Publication

Docs, however, allows technical writers the ability to create and explicitly use different (historical) versions of an item as well as branch those versions. The same topic may appear in different Publications but might have different versions, related to each other through a shared GUID. A publication's Baseline determines which versions of items resolve for use in a given published Publication.

The takeaway is that both Sites and Docs handle variation in content, but almost across different dimensions leveraging BluePrinting with inheritance/localization in Sites versus Baselines with versions/branching in Docs.

I wrapped up the exercise, which was hopefully a nice break from the slides.

Your Turn

Feel free to try this exercsise or a variation of it at your next knowledge sharing session or presentation. Previously I've had my workshop participants predict the Sites Content Manager, which seemed to have gone well. Others I've had enact the concept of Component Templates, which I will never do again. Your mileage may vary but I'd love to hear how your next exercise goes.

Have favorite drawings or diagrams of the Sites or Docs content models? Did I explain things correctly or is there a better description or good list of terminology you'd like to share?

Leave a comment and perhaps post some examples. I'm also looking for others to start exploring, sharing, and explaining the intersection between Sites and Docs! Bloggers welcome!