What I Learned Writing a Playground Book

October 06, 2016

I’m in the process of writing a Playground Book and with about ninety percent done, the last ten percent is really dragging out and taking more time than I anticipated. So to get some extra motivation, I thought I’d take a short break and talk about some of the things I learned while writing the book.

If you’re not familiar with Playground Books then you can get caught up by reading the highlight page from Apple or watching the introductory video from WWDC. In writing my book, I began with the StarterPlaygroundBook and dug into the Learn to Code books from Apple to see how they were written.

1. Start each page in a playground and move it into the book.

I found it was easier to start each page as an individual playground and get things mostly working before moving it into the book. This includes writing the markup for text, making sure the code compiles and setting up any shared resources. I found all of this to be quicker using Xcode as opposed to debugging on the iPad.

2. Create a workspace in Xcode and use it to edit the Playground book.

At first, this seemed counter-intuitive, since I thought I would mostly be writing, so why not use a text editor. In the end, much less time was spend writing compared to formatting code, creating hints, setting up code completions, and just getting each page working.

In the end Xcode using made for a simple workflow: I could create files and folders using the Project Navigator. I could quickly update the Manifest.plist each time I needed to add a page or chapter.

Other the hand, I didn’t hesitate edit in the book directly in text editor when I needed to write. The code completion for Xcode is great when writing code, but it gets in the way when you’re trying to write and communicate ideas.

Xcode Workspace

While I was writing the book, I quickly amassed a number of test playgrounds for working out small ideas for the book. I kept these in the workspace too which meant I could view and run these playgrounds while writing the book and without losing context. This was a big plus.

3. Use cutscenes to communicate dense concepts or introduce new ideas.

At the beginning of each chapter I built a cutscene using standard HTML/CSS and JavaScript. A cutscene is basically a series of slides, which is comprised of div elements and manipulated with JavaScript. I used fullPage.js to create the slides, but this is not a requirement.

Cutscenes off a nice break from coding when you’re working through a Playground book. Some ideas are best introduced with pictures and animations and cutscenes give you a free-form canvas to build on.

When working through a Playground book, cutscenes offer a nice break from coding and allow concepts to be communicated over a different medium. Some ideas are best introduced with pictures and animations and cutscenes allow a free-form canvas to build on.

On iOS, the Playgrounds app doesn’t allow cutscenes to load remote resources, so all JavaScript and CSS will need to be inside the book.

4. Write the lesson, solution and assessment together, then remove the solution.

I found it easier to write the lesson and solution together and test them out on the iPad. Once each lesson was working and correctly solved, I moved on to writing the assessment. Because the assessment logic needed to scan through the Playground for a correct solution, having each solution already written made it this much easier– I didn’t have to add the solutions in after the fact. Writing the assessments involved testing them against different solutions, to make sure hints were offered at the appropriate times.

Having the solution written made it easy to then create hints for each page. These essential for helping the reader along and easing frustration when things aren’t quite working.