Starting in the latest betas, playgrounds have introduced a Markdown-like commenting standard for creating rich text interactive documents. This support replaces the earlier approaches Apple used to create the Guided Tour and SpriteKit Balloons walkthroughs that got people so excited about mixing interactive code with descriptive overviews

Each playground can now be shared as a single stand-alone document, with its support material embedded directly into the file. I’ve put examples up on github (the filters and OSX playgrounds) if you’d like to see what this technology looks like in its current form.

As I’m learning the new system, it’s making me focus on what it takes to design an engaging document. There are many practical uses for playground documents. You might teach algorithms, document an API, or provide usage examples for a particular technology. In each case, you build a narrative with live embedded code segments interspersed in the text.

At the same time, playgrounds also tell stories. A well-designed playground expands your user’s experience beyond source code comments. Source code, no matter how well annotated, doesn’t provide the same natural flow or the opportunity to explore the way a playground’s interactive document does.

So what does it take to accomplish this? Here are some preliminary thoughts.

The playground has to focus on the interactive. Consider how your user might adjust and interact with your code. Provide text-sourced hints on what to do and what the user should expect to happen as they do so. Suggest tweaks and adjustments your user might use to explore.

A playground should step outside of a documentation page and bring something to the table that you cannot offer in the existing medias of print, web pages, and ebooks. Interactivity and live code interpretation are what set playgrounds apart from these other information delivery platforms.

The playground should satisfy the senses. Offer your readers something beautiful that goes beyond simple text descriptions. Whether animating with SpriteKit or building simple UIImage instances, integrating programmatic aesthetics elevates the experience from (if you don’t mind me abusing a metaphor) a PowerPoint to a Keynote experience.

Distinguish reference from pedagogy. Differentiate your narrative from code comments. A playground’s rich text may share markup tasks with Quick Help but their underlying goals are distinct.

Quick Help annotates symbols for easy reference. Playground documents instruct in an interactive environment with immediate, live feedback. One is a reference materials task, the other is a guide task. The language, the structure, the examples, and the content should follow from those goals, with a playground offering a far richer set of descriptions and suggestions intended to teach as well as showcase.

So what do you think? Are there design points that I’ve missed? Or am I simply wrong about some of these suggestions? Please ping me by email or twitter or leave a comment and let me know.