For the last year or two, I’ve come to realize that the number one thing that makes it harder for me to do my job is documentation. Or, more specifically, the utter dearth of documentation that Apple provides for its platforms.

As a developer, Apple provides us a series of tools — APIs — that allow us to make apps on iOS, iPadOS, macOS, and tvOS. In many cases, it’s fairly straightforward to figure out how to use these APIs. There’s only so many ways you can use a screwdriver, and similarly, in many cases there’s only one obvious way to use an API.

However, as users rightly demand more complicated and fancy apps, the APIs often need to get more fancy and complicated as well. Suddenly you look up and, instead of only using screwdrivers and hammers, you’re using power tools and complicated saws, and everything is much more fiddly than it once was.

With real power tools, you expect to receive an owner’s manual, which explains how to use the tool you’ve just purchased. A rough analogy exists for APIs, insofar as most platform vendors will provide documentation. This is basically the “owner’s manual” for that API.

Apple’s documentation has, for years, been pretty bad. Over the last couple years, it has gone from bad → awful → despicable → embarrassing. All too often, I go to research how to do something new, and use an API I’m not familiar with, only to be stymied by those three dreaded words:

No overview available.

This is Apple’s way of saying “Fuck you, figure it out”.

No overview available is so bad that a popular Apple resource — itself something that probably shouldn’t have to exist — used it as its namesake for a single-serving site to highlight how bad Apple’s documentation is.

The march of progress doesn’t help, either. As my friend Adam Swinden pointed out to me on Twitter, as old APIs get deprecated, often times Apple can’t be bothered to include documentation for the new ones. Check out the difference between this API and the one that replaces it.

No overview available. Fuck you, figure it out.

A couple years ago, two new phenomenal APIs were introduced around UICollectionView:

• Diffable data sources
• Compositional layout

For at least a year — maybe two — far and away the best documentation for these new and important features was hidden in the header files. That’s despicable.

On this week’s Under the Rader, my pals Marco and Dave continued their arc of Marco’s transition into Swift and SwiftUI. In the episode, both Marco and Dave really eloquently described some of the absolute pain Apple developers go through in trying to understand how to use the tools Apple provides.

At the bottom of this post is a transcript of their thoughts, which has been lightly edited to make things a little more clear for the written word. Overcast timestamp links are provided at speaker transitions, if you’d like to listen to it from the horse’s mouth.

No matter what, I’ve been banging on this drum for years. I haven’t a clue what the problem is at Apple.

• Is the documentation team not given the time to react to new APIs? (I’d buy it.)
• Is the documentation not considered a prerequisite for shipping? (I’d definitely buy it.)
• Is the documentation team really bad at their jobs? (I doubt it.)
• Is the documentation team too small? (Likely.)
• Is the documentation team stymied by politics or in-fighting? (Probably.)

Whatever the problem is, it needs to be fixed. This is a problem that has been festering for years, and the pot is finally boiling over.

Under the Radar Transcript

Marco: Having to learn SwiftUI is, first of all, the learning resources out there are still terrible, because it’s such a young language/framework/method of even thinking about things. It’s so young, and it changes so frequently — similar to the early days of Swift — that a lot of the tutorials, sample code, or Stack Overflow answers that are out there are no longer even correct. Because something has changed since when they were written last year, and now. Or the answer was posted during a beta, and in a later beta even that same year, the name of a class changed, or the way you’re supposed to do something changed. It’s so early, still.

This is a time when you really feel how much we need better documentation support from Apple. One of the great things […] about PHP 🤣 is that PHP has always had exceptional documentation on its website.

On php.net, you an search for any function, and editors would build in hotkeys so, in Textmate, I can hit ⌃H and it pops up a documentation window from php.net about whatever function name I have my cursor on at that moment. There’s always been great documentation there. On the documentation pages — in almost every function in the language, which is a lot — there are example code snippets on documentation pages. And there’s comments! So even if the example code doesn’t quite there for you, or doesn’t answer a quesion you have, the comments usually do.

This is something that I really wish Apple’s documentation would have — these little usage examples — because they really can help explain and show, better than just a pure API reference, how to do something. Or what a function is for.

As we move into the land of SwiftUI, and Combine, and all of these higher-level concepts, a little more complicated things — this is also going to apply similarly once Swift gets its whole async/await thing, presumably in a year or two. It becomes harder to understand a lot of these concepts, because they’re so abstract, and they have really simple-sounding names, and it’s really hard to tell what this does, how to use it, and so we all end up having to go to StackOverflow, and tutorial blogs, because Apple’s own documentation — [if] it’s even there, and that’s a big [if] — is so bare-bones and minimal, it’s like Jony Ive designed it —

Dave: …it’s a big white room…

Marco: Yeah, it’s a big, white, empty page. And it’s like, “this type is to do this one thing”, and then there’s no other context; no example showing “when would you use this”, “how do you use this”, “do you call this in a certain way, like as a constructor”.

You can get so much value out of those little tiny snippets on documentation pages, like what PHP does. Like, “here’s a four-line example of how to use this thing”. And I wish for that so much as I’m learning this stuff.

I’m seeing — and I would imagine this is how beginners see almost all parts of programming — because I am such a beginner at Swift and SwiftUI and at these concepts that SwiftUI is built upon — I’m seeing what it’s like to be a beginner for the first time in a while. I would benefit so much from better documentation, and to have — presumably at Apple — a pretty strong effort to not only write the documentation, but then to update the documentation as the language changes.

This is the problem when you have these young languages that are greatly in flux, or these young frameworks that are greatly in flux. If you’re relying on tutorial blog posts, and StackOverflow answers, well those go out-of-date pretty fast, as I was saying earlier. It’s nobody’s full-time job at Apple to make sure that all these tutorial blog posts that are out there can be updated when the language changes, so they mostly just aren’t [updated]. Or, some of them are, some of them aren’t, and it’s hard to know what you’re going to land on when you find it.

Even then, SwiftUI, for as cool as it is, and as much attention as it’s gotten from language nerds over the last year, there is very little out there about it; there is very, very little. There’s even less out there that goes beyond trivial use cases. For instance, if you have to make a tech demo with SwiftUI, and you have to have a button state that changes, and increments a number or whatever, great! There’s a million blog posts out there about that.

But then, once it’s like, “Okay, how do I tie this into the rest of an app?” That’s a real app, that has actual needs like persistent storage, different screens, and everything. Once you add the complexity of real-world apps, most of these tutorials can’t cover that, or don’t cover that. So, I’ve had such a time, Dave, trying to adopt SwiftUI from these trivial little tutorials that people have, or that Apple has in WWDC sessions, to try to actually build “How do I connect that to my database”? “How do I connect that to my downloader or my sync engine”? There’s been so much of that. And I think I’ve finally got it, but man is it non-trivial and non-obvious, and there’s so many weird little pitfalls.

Dave: I absolutely feel your pain, though. What’s so frustrating to me about this […] there are absolutely a couple of really tremendous SwiftUI resources online. For me, it’s Hacking with Swift by Paul Hudson. Like 80% of my SwiftUI knowledge has come from his site, and his videos. […] He has this great process where he’ll make these videos that show you one level beyond the trivial example, where you end up with something that’s like… Trivial+. It’s not a full-blown example, […] there’s still those rough edges that you’re talking about. I definitely continue to run into that. Where I want to do something a little bit more than the obvious case, and then, it’s like you’re jumping off this cliff, and it’s like “good luck”. […]

I remember back at the beginning of the spring, I remember there were a couple of the educators in the Apple community. People who are typically on the conference circuit, they speak at a lot of the conferences, and they do workshops, and educators like that. And they were saying “You know what? We’re not going to able to travel for all of 2020, it seems. We’re not going to be able to do conferences; we’re not going to be able to do a lot of things. Hey, Apple, There’s a lot of really talented educators in your community who have a lot of spare time. It’d be a great thing if you took advantage of that.”

It’s kind of sad that now that we’re sort of toward the end of the year, it doesn’t seem like they did. It doesn’t seem like there was any kind of movement on that, to leverage all of these people who are excellent at explaining things, at creating example apps. At doing this work in a way that would help people in your circumstance, in my circumstance. I really feel for the people who are coming at SwiftUI without decades of programming experience. If this was the first app you’re learning, in some ways it’s easy-ish. […] A really basic SwiftUI app is really easier to build, probably, than the most basic UIKit app. But, as soon as you start getting beyond that, it gets so complicated so quickly.

I also think of how — it’s so difficult with documentation — is how, the people who are best able to make documentation for a new platform are the people who make the platform. Because they can work on the documentation, and have it available at the process of it being released. […] I feel bad for all the Apple tech educators, [when] a new SDK drops, or a new beta releases, and then they’re just like, not-sleeping for three days trying to frantically update all their stuff, and get new stuff covered. They do a great job — and I appreciate it — but this doesn’t have to be frantic.

This could be, the documentation team at Apple has been working on this in concert with the people writing the APIs for months. So on day one, here’s a great set of examples, that show code about how to use this.

You’re exactly right — especially about SwiftUI — the nature of it is that traditional documentation… If you go to the documentation for Text in SwiftUI, the View, the number of different modifiers you can apply to that View is probably in the hundreds — if not more. But, having just this gigantic list of all the things you could possibly ever do to a Text isn’t helpful. What you want to see is, “Okay, how do I do text that looks like this?” “What if I want multiline text?” “What if I want multiline text that has only this many lines, and then is aligned in the middle?” Doing that kind of stuff, you need examples. I don’t think the total number of cases that people actually use is that wide. I feel your pain.

Offering to discuss Top Gear and/or Disney World is a pretty reliable way to get me on a podcast.

In this week’s episode of My Hill to Die On, American expats Nate and Ryan take me on a historical journey explaining how they both ended up living in Japan, reconciled some differences between Walt Disney World and Tokyo Disney, and eventually discussed one of my favorite segments on Top Gear: the race against the bullet train (see also part 2).

Also in this episode, Nate and Ryan have me try some uniquely Japanese snacks that they had shipped to my house. Needless to say, that was quite an adventure.

Curiously, in these unprecedented times, I feel like I’m both considerably more and considerably less busy all at the same time. Because of that, I neglected to mention a really fun guest appearance I did last week.

My buddy Tyler Stalman is in many ways the man-about-town, and I mean that in the most complimentary way possible. In a semi-tradition we semi-accidentally started last year, I joined him on The Stalman Podcast to discuss last week’s Apple event.

This time, however, Tyler asked me to also record myself while we spoke. As someone who never has video on while recording, doing so was quite a change of pace, but I think it came out quite well.

Some behind-the-scenes trivia: my recording colossally failed right at the tail end of our talk, leaving a mess of an edit for Tyler. (Sorry about that, again, buddy. 😞) I bet you won’t be able to tell where though.

This week I joined my pals Jean MacDonald, Dan Moren, and Mikah Sargent on Clockwise. On this episode, we discussed our hopes for next week’s Apple event, how to find joy in these joy-Liss times, how we use NFC, and how virtual conferences have helped us rethink conferences in general.

Clockwise is fun and fast. You should give it a listen.

About a month ago, I decided to sunset Vignette.

This was a decision that was a long time coming. In short, due to changes in Facebook, Instagram, and most especially Twitter, Vignette cannot work nearly as reliably as I would like. As such, I have decided to pull it from sale, worldwide. It isn’t right to charge money — any amount of money — for something that no longer works properly.

It Begins With Facebook

As with many bad stories of late, this one starts with Facebook. Starting probably eight-ish months ago, I kept getting regular reports from users that Facebook integration wasn’t working. Whenever I tried it at my desk, it worked no problem. Of course. For probably half of Vignette’s existence, and some unknown subset of Vignette’s users, Facebook never worked better than 50/50.

Curiously — and still unexplained — I also heard consistent reports from users that switching Wi-Fi ↔ Cellular resolved their Facebook issues. For the life of me, I couldn’t (and can’t) wrap my head around why that would be. I started going down the rabbit hole of iOS content caching, but never made heads or tails of it.

Enter Instagram

Not long after Vignette shipped, I had to start throwing best practices to the wind, and having Vignette masquerade as Instagram itself. This is not something I ever felt great about. Shortly after I started faking being Instagram, I realized I needed to update the mechanism I used to fake it. Already, the cat-and-mouse game started.^[1]

Eventually, I settled on something that seemed like it was reliable, but it was also undocumented, liable to be taken away at a moment’s notice. This didn’t feel good to me as a developer, and surely isn’t the path to satisfied users.

Twitter’s Nail in the Coffin

For the entirety of Vignette’s life, outside of the generally-only-used-by-nerds Gravatar, and Github, Twitter was the most reliable and straightforward way find a user’s profile picture. All you needed was a specially constructed URL, and you were golden.

For example, here was mine:

https://twitter.com/caseyliss/profile_image?size=original

This used to be available to anyone, no matter if you had a Twitter account or not, and whether you were logged in or not. It was… glorious.

Suddenly, a couple months ago, Twitter turned this feature off. Going forward, I had two choices:

• Force users to log into Twitter via Vignette, which is somewhat antithetical
  to my whole privacy focus
• Treat Vignette as a full-fledged Twitter client app, which would limit me to
  900 requests per 15 minutes for all Vignette users in aggregate.

Options

I felt like I was between a rock and a hard place. Not to mention the support burden for Vignette seemed to be increasing over time, probably due to the above unreliability.

My only choices, as far as I could see, were:

• Start allowing login via Vignette to all of these services. This would:
  • Presumably fix the unreliability
  • Be an immense amount of work
  • Probably not be financially prudent
  • Be somewhat against my whole privacy stance
• Retire the app. This would:
  • Largely eliminate the support burden
  • Prevent any new users from buying an app that doesn’t work properly
  • Eliminate what was becoming a tremendous mental burden

I chose to retire the app, by removing it from sale.

It will still be available to existing users in its most recent incarnation, but new users cannot download nor buy it.

I briefly considered making the app free, but a non-functional free app is only marginally better than a non-functional paid app. The support burden for a free app is also non-zero, where the support burden for a retired app approaches zero with each passing day.

Ultimately, discussing Vignette with my co-hosts on episode 386 of my podcast (the conversation begins at 1:34:33) led me to the conclusion I knew but wouldn’t admit to myself: I must retire Vignette.

Thank You

To anyone who purchased Vignette, please accept my heartfelt thanks. Vignette’s launch was beyond my wildest dreams, but as with most iOS apps, that peak fell fast and hard. I didn’t expect for its life to be so short, and I am disappointed by it. Nonetheless, Vignette made a tangible difference for my little family, and I will forever appreciate all of my customers. Thank you.

I’m super bummed right now.

Normally, I’d be freshly back from WWDC, reinvigorated and ready to take on a new year of development.

But thanks to COVID-19 ruining… gestures wildly… I’ve missed out on seeing so many of my friends from across the world in California. I’ve missed out on seeing my family on the day before WWDC, one of my favorite annual traditions. I’m just… sad.

However, thanks to the work of Sam Henri Gold and a ton of volunteers, I have something to be excited about: the Indie Sticker Pack.

Indie Sticker Pack is a physical sticker pack of over 100 app icons from some of your favorite indie apps. I was very flattered to be asked to include Ste Grainer’s execellent work on Peek‑a‑View in the Indie Sticker Pack.

Already cool enough, Sam and team have decided to donate 100% of the proceeds to two great causes:

• World Health Organization’s COVID Relief Fund
• Equal Justice Initiative

I’m super flattered to be a[n insanely small] part of this, and super glad that my dear friend Ste was so willing to throw together new versions of the Peek‑a‑View icon at the last second.

Go get yourself some stickers. Everyone likes stickers. Everyone likes donating to a good cause. It’s a win/win.

A couple weeks ago I was on that week’s episode of Clockwise. I completely blanked on mentioning it here.

On that episode, I joined my friends Dan Moren and Mikah Sargent, and was lucky enough to share the proverbial stage with my friend Jean MacDonald as well.

We discussed, in 30 minutes, Apple’s possible lack of inclusion of headphones in the next iPhone, places we want to go when quarantine is over, online gaming, and watching movies with friends.

Clockwise is fun and tight; if you’ve never listened, you should.

Over 100,000 Americans have died from COVID-19, a disease that we were told will be eradicated before it’s a problem. By the man who has decided to take America out of the World Health Organization. Our neighbors and community members are protesting — and rightfully so — the deep, deep racial inequality in this country. The man in the White House told us after what happened in Charlottesville — my former hometown — that there were "very fine people on both sides”.

Black lives matter.

All lives don’t matter until Black lives do.

We are told that the United States government is classifying a group that is opposed to fascism as a terrorist organization. Our government is now… anti-… anti-fascism‽ Does that make us… pro-fascism‽

We are being told that allowing mail-in voting is dangerous by the very people who fear so deeply the results of that style of voting. Their motives are so transparent.

If this is the America you wanted in 2016 — our Black community members demanding to be treated like humans, our hospitals fighting for the lives of everyday Americans, our doctors doing their jobs without the protective equipment they need to keep themselves safe — then I don’t know what to say to you.

For me, I hope and believe we can do better. And no matter what I feel about the nominee on the blue side of the ticket, you can bet I’m going to vote like hell in November.

Because all lives don’t matter until Black lives do too.

Because Black people deserve better.

Because people of color deserve better.

Because the LGBTQIA+ community deserves better.

Because so many other marginalized communities deserve better.

Because our doctors and nurses deserve better.

Because our teachers deserve better.

Our children deserve better.

We deserve better.

I’m going to vote like hell in November. I hope you do too.

This week I joined Chris and Glenn on their Starport75 podcast again. We spent the episode discussing how, but mostly when, Walt Disney World will reopen. Naturally, I’m completely unqualified to come up with answers to such questions, but that’s never stopped me before.

At the end, we also have a bit of a “bonus round”: the boys ask me about my soda preference, and how I would spend an hour alone in Disney. I then turn the tables on them, and ask the boys which Disney restaurants are unreasonably beloved.

As with last time, I really enjoyed discussing all things Disney with Glenn and Chris; if you’re even moderately interested in Disney, you will too.

Over the last few weeks I was [briefly] featured on the last four episodes of the Stacktrace Podcast. Hosts Gui Rambo and John Sundell interviewed several independent developers, such as myself, and put together segments around common topics.

On episodes 74, 75, 76, and 77, you can hear some of my thoughts about coming up with an idea for an indie app, creating it, marketing it, and more.

Stacktrace is a podcast for nerds, by nerds, and if you’re in my line of work, I bet you’d really enjoy it.