Creating an App Walk-Through for the Playgrounds App

Swift Playgrounds Icon

Creating a walk-through for Swift Playgrounds can sometimes feel like wrestling a bag of eels in a room with all the lights burnt out.

Walk-throughs are a great way to set up content that learners can go through at their own pace as if they had a very patient senior software engineer sitting beside them, walking them through the code. I’ve written a few on my Adventures feed ( and they’re such a good way to help focus on specific app development techniques or tools people may have been asking about, but I’m not necessarily going to be there in the room with them.

There is a great WWDC talk from 2022, when the app launched, walking you through how to create content, but it’s not always so easy:

WWDC 22: Create engaging content for Swift Playgrounds:

I’ve recorded a video of many of these steps, and a few troubleshooting notes down below, even, about some common things you might want in your walk-through.

Walk-Through Surgery

First, you’re going to be doing some surgery inside your app’s folder structure, and they demo it using the Finder to create an App folder and they put everything in there, except for the Package.swift file, which is the file that tells the Swift compiler what the project should look like, how to build it, what to include, and all the rest.  

You should then create a Guide folder in the same folder that now contains the App folder (it’s also called a module, if you listen to the video above).

So your app looks like this:


However, this isn’t going to display a walk-through, just yet.

In the Guide.tutorial file, you’ll need something that looks like this:

@GuideBook(title: "Get Started with App Walk-Throughs", icon: title.png, background: background.png, firstFile: MyApp.swift) {
    @Guide {
        @Step(title: "Get Started with App Walk-Throughs") {
            @ContentAndMedia {
                Our first test step...

Even if you don’t have the title.png or background.png files, you need to have those parameters in the GuideBook().

This guide contents above is the bare minimum with which I’ve been able to get a walk-through to appear. From there you can follow all the advice and tips in the WWDC video above, and you’ll have a chance to build some amazing content.

Going Further 

Now, if you get to the stage where you want to add resources to your guide; images, localized strings, a glossary, you may run into some further issues getting that walk-through to display.

If you try to add a folder in Playgrounds called ‘Resources’ you’ll hit your first roadblock, because Playgrounds won’t let you, because that’s a reserved folder name.

So over to the Mac we go.

As I mentioned in a previous post, you can open Swift Playgrounds apps in Xcode on the Mac ( We don’t quite need to go that far, but there are some handy things Xcode will help you create if you want to build localized walk-throughs.

On the Mac, right-click or use the action menu to show the package contents of your app.

In the Guide folder, create another folder called Resources. Here we can drop images to display in the guide, like the title.png and background.png above.

If you do want to take the next step and add a localized strings file, just a warning, you will have to dive into the Package.swift file and add a property to the top level:

    defaultLocalization: "en",

(Or whatever your default localization will be.) Otherwise Playgrounds will complain that you need this key so it knows which strings to load for your walk-through.

If you Show Package Contents on the app and then double-click the Package.swift file. It should open up in Xcode, if you have that installed, and you’ll add that line above just beneath the name: “MyApp”, line.


One of the things I always struggle with, when confronted with those “Failed to create… SPCGuideBook.Type” messages, is getting the welcome message to show. The thing I’ve found, to get a Welcome Message to show up properly, is that you need to pick a View file, I’m almost certain.

So if your tutorial file looks like this:

@GuideBook(title: "Get Started with App Walk-Throughs", icon: icon.png, background: background.png, firstFile: MyApp.swift) {
    @WelcomeMessage(title: "Get Started with App Walk-Throughs") {
        Welcome to the show
    @Guide {
        @Step(title: "Get Started with App Walk-Throughs") {
            @ContentAndMedia {
                Our first step...

it’s likely you’ll see the error message about it not being able to be loaded.

So you might try changing your tutorial file to look like this, instead (note the change in bold):

@GuideBook(title: "Get Started with App Walk-Throughs", icon: icon.png, background: background.png, firstFile: ContentView.swift) {
    @WelcomeMessage(title: "Get Started with App Walk-Throughs") {
        Welcome to the show
    @Guide {
        @Step(title: "Get Started with App Walk-Throughs") {
            @ContentAndMedia {
                Our first step...

Remember to close and reload your playground apps when you change the walk-through… that can be one of the biggest hassles about authoring app walk-throughs, but once you get a walk-through loaded it’s usually far, far easier to troubleshoot little missteps here and there.

Moving your app from Swift Playgrounds to Xcode

Swift Playgrounds Icon

There comes a time in every person’s life when they find they need to move from their beautiful little app they created in Swift Playgrounds to the big, bad world of Xcode.

Okay, maybe not every person’s life.

But there might come that time.

Getting it to your Mac

First off, you need to get the Playground app over to your Mac, and my personal favorite way is with AirDrop.

You can share your Playgrounds by tapping on the title, if you have it open in Playgrounds, or you can choose Select and then Share from the screen with all the playgrounds visible. Once you’ve AirDropped the app to your Mac, you’ll see a file that says (if you have show file extensions turned on) My App.swiftpm.

And you can open that in Xcode, by right-clicking on the file (or selecting it in the Finder and choosing the Action menu and selecting Open With…


But when would we want to do something like that?

More Features from our Development Environment

Well, sometimes we want to take advantage of some of the pro features Xcode has that Playgrounds doesn’t. Things like:

  • Powerful debugging capabilities;
  • Instruments for analyzing your app’s performance;
  • Simulators of all kinds of iPhone, iPad, Apple Watch, and other devices;
  • More information on the bigger screen of your laptop with navigator panes, inspector panes, preview canvas, code editors, and more;
  • Source control integration with platforms like Github…

Especially if we’re familiar with Xcode, we may be super comfortable with all the tools it has built in to help us build our apps quicker and more efficiently.

With this as our main reason, we’re still in pretty good shape. We can leave the app in its .swiftpm project file format.

When we do this, it means we can edit our app in Xcode on our Mac and then AirDrop it (or save it in iCloud) to edit on the iPad in Playgrounds, as well.

We Need More Advanced Features for our App

We can get incredibly far with Playgrounds and app development, even shipping apps all the way to the App Store and selling them!

But there are a few features of Xcode-based projects that might entice you to move over, or you might need to move over, to implement certain features in your app. For example:

  • Easier device and orientation support – Xcode projects make it easier to tick a box and restrict an app to iPhone Portrait view or any number of combinations;
  • Even more capabilities, like iCloud support, Apple Pay support, custom Fonts, Game Center…;
  • Multiple targets, Xcode Cloud support from the development environment;
  • Storyboards and UIKit support with Interface Builder

Making the Leap

If you do decide, yep, I want some of those extra features, so I’m moving to Xcode, just a word of warning: you can’t AirDrop an Xcode Project-based app back onto your iPad and work on it in Playgrounds.

In the video below, I show you one way to do this, and some ways to get out of the trouble you might find yourself in with some common issues that arise.

You can get pretty far with Swift Playgrounds. In fact, at the start of the video I show you how to add functionality to your Playgrounds app using packages, and the way to do the same in Xcode.

But if, for any of the reasons listed above, you feel like you need to move to Xcode, or just want to check it out, the video will help you see how that can be done.

Best of luck, and if it’s your first time using Xcode, welcome to the Show!

More Advanced Apps: Segues and Navigation Controllers

We’re in the thick of a hackathon project and some students are plowing ahead with their prototypes and looking to turn them into full-blown apps.

In this new video I walk you through a pretty common scenario.

Many of our apps are going to have more than one screen. And what appears on subsequent screens is going to depend on what a person has tapped on or possibly something they’ve typed in or a way they’ve interacted with a previous screen.

So we need a way to pass data from one screen to the next. This topic is covered in Develop in Swift Fundamentals in Lesson 3.6, Segues and Navigation Controllers.

Our segue will be our go-between our original, or our source, view and our destination view. And there’s a little bit of sort of magic* involved.

Check out the video below for some steps through creating another View Controller that will be our destination view, the code that backs it, a connection to the new view, and how to wire up passing data between the two.

Best of luck building out your more complex app!

* Well, not quite “magic.” More like hooks into the very inner life of our iOS app like we’ve got a pair of X-ray specs and suddenly we can see all this cool underpinning of our apps going on that maybe we didn’t realize was there before.

App Development Workshop Follow Up

I hope you’re all enjoying the summer. It’s been sunny and warm in Ireland, thank goodness, so we’ve been spending our time outdoors as much as possible!

But we did get inside to do some coding when we recently ran a series of workshops to introduce new coders to the Develop in Swift series as part of an app development challenge.

If you’ve been reading Develop in Swift Explorations or Develop in Swift Fundamentals , I’ve recorded a video that takes some of the concepts and an approach to building an app and walks you through one way to do it.

I give you some pointers to lessons in Fundamentals or projects in Explorations that you might explore to learn more.

Check it out and we’ll be back soon with some more videos and coding tips!

WWDC21 Wish List

Last year we had a little wish list for WWDC, so I figured I would take a look at what we’d love to see today.

Last Year

Well, first, what did we get last year?

From our list, we did wind up getting new books, a whole load of them! Some didn’t ship during WWDC, but now we have Develop in Swift Fundamentals, Develop in Swift Explorations, Develop in Swift Data Collections, Everyone Can Code Adventures. That’s quite a lot of stuff to read through!

We even now have a huge resource in the App Design Workbook, which introduces app design process as well as a bit of SwiftUI in Playgrounds to keep you busy.

One thing on our wishlist was more dev on iPad, and Swift Playgrounds is still getting a lot of love, which is excellent, and getting more interesting with each release on both the Mac and iPad.

This Year’s Wish List

Okay, so what would we love to see this year?

Obviously I’m biased towards things that will help us teach coding, but I’ve got a few more this year I’d love to see under the proverbial WWDC Tree.

Swift Playgrounds

  • I would love to see an easier way to author Swift Playgrounds (like last year). I’ve run two sessions on creating Swift Playground Books, one with the Swift Playground Author Template and one by copying an existing playground book.
  • I loved the sessions on Swift Playgrounds last year, in particular the first in the Swan’s Quest series. It would be amazing to see more this year. Using those sensors is pretty amazing and eye-opening for a lot of students.
  • A Swift Playgrounds Community site: some sort of way to easily share Swift Playgrounds with students, fellow developers, where you can just show off your work easily, would be amazing. Think of it like a dynamic Swift Playground feed people could publish to easily from within the Swift Playgrounds app…

Xcode and teaching Develop in Swift

  • If Xcode had a remote sharing option, so the teacher or co-coder could observe one person typing, that would be an amazing addition to teaching coding. It’d be icing on the cake if we got the same with iPads and Swift Playgrounds, and I need to have a look at the Classroom app update to see if maybe that’s already done.
  • Some of these collaboration features would be a real boon to teaching people how to code, especially in as rich an environment as Xcode, so any more integration with Github, remote sharing, and the rest would be much appreciated
  • A web-based version, for those folks who want to try out Swift and app development, would also be amazing. I really like, especially with its implementation of the Swift REPL and readLine()… but it never hurts to have more options.

RealityKit and Reality Composer

  • Lastly, and by no means is this an exhaustive list, I would really, really love to see the ability to support more than one image anchor in a Reality Composer scene. We’ve had a few questions lately about supporting them inside the one Reality Scene… and while there are ways to handle this (multiple scenes for each image anchor you want to support, using code and loading ARImageAnchors yourself), this would be a really fun addition to an incredible app. Reality Composer makes it so easy to create engaging, robust experiences with very little to no code already, but a few additions would just ice the cake.

Now You


That’s our list, what do you want to see from WWDC21?

Teaching Develop in Swift Online – June Edition

We’re going to be back (online) teaching you how to teach the Develop in Swift material — Explorations, Fundamentals, and Data Collections — in June!

If you’re an educator thinking about teaching Swift and app development (or already doing it), this is a really fun, packed week.

Coming June 21st!

We’ll be holding hands-on workshops, lectures from the books, special sessions, and some takeaway projects you can run with your own classrooms.

Teaching App Development with Swift runs from 21-25 June 2021, from 8am to 16:30, Irish time, each and every day. You get a chunk of time in the middle of the day to work on your projects and finish anything you were working on in the workshops. And then in the afternoons we have some app showcases planned, where you can show off your work!

You can register here, and it’s all free.

We’ve brought back some old favorites and added some new activities that I really think you’ll like, so hopefully we’ll see you online!

Teaching and Presenting with Keynote

When I’m teaching teachers how to teach coding we spend a lot of time in Keynote.

The excellent Develop in Swift series, from Apple, comes with a whole set of keynote files for presenting nearly every lesson in the book. If you download the teacher materials from the Teacher Guide, you’ll find the slides, presenter notes, animations in the keynote files already, as well as Xcode playground-based labs for your students to try.

Now, if you’re new to the Mac, you might to be super familiar with Keynote. So I’ve put together a short video which you can watch below, or you can head off to YouTube, to help you orient yourself in Keynote.

I show you how to present on a Mac with only one screen so you can see your presenter notes, too. If you have an iPhone or an iPad, you might want to watch the Using Keynote Remote to Present video to see how to use the Keynote app on your device to remote control your Mac’s presentation.

If you’ve got all that down, but need help sharing your screen over WebEx, well, I’ve got a video for that, too.

Of course, if you’re new to the Mac or Keynote you’ll still need to get some hands-on practice, but at the very least this video above will start you out on the right foot!

Teaching Develop in Swift – March 2021 Edition

Are you a teacher who is trying to figure out how to teach coding, and app development in particular?

Are you a coder who feels like you could help people learn how to develop apps?

Does this feel like I’m leading you somewhere with all these questions?

Develop in Swift

Well, I am!

I’ll be running a week of intensive training in Teaching Develop in Swift Online with Apple in the first week of March.

Register (for free!) here:

We’ll give you a pretty good look at the Develop in Swift curriculum, which is aimed at secondary school to university level students.

They’re a series of free e-books Apple has produced to introduce you to the world of coding using their programming language, Swift. It’s the same coding language folks use to write wildly popular apps for your iPhone, iPad, Mac, Apple Watch, and AppleTV.

Develop in Swift Explorations introduces coding in a broader context. It’s designed to reveal coding to those people who might have never considered all the places we experience code someone else has written. We’ll build some of the projects in this book each day, including the really fun QuestionBot. This will form the basis for a project you can run with your own class.

Develop in Swift Fundamentals is aimed at computer science students (though it’s not limited to them!). It’s like a traditional programming class with 3 more projects to build. We’ll also build these in class during the week. I love that this material teaches you Swift and how to build an app. It’s not just a matter of putting code in the right places, it’s about working with others, coming up with a plan for delivering something.

Develop in Swift Data Collections is the last in the series and covers even more advanced stuff to make your apps look amazing and do incredible stuff.

The Week

We’ll have lectures each day from the material, hands-on workshops on projects from the books in the morning. Some time in the middle to work on projects and get food. Then showcases and group discussions in the afternoon. Each day we’ve got special guests coming to talk to us about design, technical topics, or the books themselves.

It should be a ball, and we’ve got some fun, interactive elements planned for it.

So if you’re a coding teacher, a developer who wants to teach, or a teacher who wants to teach coding, come along with us!

Register (for free!) here:

There’s still space, but not for much longer…

Middle Schoolers Exploring Coding

For those who aren’t as interested, they’re still going to be learning determination, perseverance and trial and error.

from the ReMarker, February 2021, “In a Growing Industry” by William Fitzpatrick Junior of St. Mark’s School of Texas
What is coding?

Issu had an interesting article from a middle school in Texas about the success of their coding program, which runs from fifth to eight grade. They equip their students with designated computer science teachers in all the grades, which is a huge leg up.

I think it’s a brilliant program they have for the kids, but my favorite piece of the article was the quote above. “For those who aren’t as interested.”

That’s a huge segment of the population. Those people who don’t know that much about coding, or maybe they do, and they find it’s just not for them (or don’t know if it’s for them or not).

In the Beginning

In the beginning of your coding career, whatever form that takes, you will likely find some use for coding that suits your needs. It’s how I started.

Where some people might thrill to solving puzzles for the sake of solving them, others may need a specific need met. This is why I love seeing the cross-curricular work that folks like Michael O’Kane, Giovanna Busconi, and Daniel Budd (and more) have put out there to teach coding under the auspices of history, or literature, or math. Maybe that’s how you started: you saw an application this skill in a field completely separate from computer science itself.


Apple has an excellent curriculum designed for these sorts of folks: they might not fully get what coding is all about, but they use technology in their daily life, as most of us do, and could potentially benefit from another tool in their tool belt.

Develop in Swift Explorations:

It’s called Develop in Swift Explorations.

You need a Mac and Xcode 11 (at least), but this course will introduce you to coding in the context of your daily life: how the device you use, like your phone, uses coding and how much of our daily interactions rely on coding and processes we might not have even thought of!

Like Everyone Can Code and the other Develop in Swift books, it’s a self guided book with student resources to download which include labs. At the end of each lesson you have a lab to complete that will help you practice your new found skills.

Explorations for Teachers

If you’re a teacher who wants to try using this material with your students (it’s aimed at high school or university students), I’m running a free week-long session in March that might help.

We’ll cover the Explorations curriculum, as well as the Develop in Swift Fundamentals course. Fundamentals is more of a computer science course, but still a great introduction to coding. We take you through the books and get you familiar with the material and ways you can teach it.

You can register here:

This is a golden opportunity to meet some amazing teachers and coders. We’ve had some incredibly diverse audiences in the past, and this time should be no different. But it’s also a chance to ask questions about the material, and how we teach perseverance and determination. It’s going to be intense, with lectures and workshops in the morning. Then we’ll have a bit of homework and some showcases, group discussions in the afternoon. You’ll get the chance to meet the instructors in smaller groups to ask pointed questions or just have a chat. And each evening we have a special guest of some stripe scheduled.

So if you’re a teacher, you’re more than welcome to come along with us! Sign up at the registration link above, make sure you have a Mac handy, and we’ll start you on your coding adventure.

If you have any questions, feel free to join our Teaching Swift Slack instance, where you can drop me a note.

I hope to see you the first week of March!