Under the Radar

94: Release Notes


00:00:00   Welcome to Under the Radar, a show about independent iOS app development.

00:00:04   I'm Marco Arment.

00:00:05   And I'm David Smith.

00:00:06   Under the Radar is never longer than 30 minutes, so let's get started.

00:00:09   So today we wanted to talk about release notes, and I guess more generally about kind of like launch communication strategies and approaches.

00:00:18   Oh, so we're not talking about the podcast release notes or the conference release notes. We're actually talking about release notes.

00:00:22   We're talking about the actual things that you write and publish when you release an update to your application or you launch it initially.

00:00:29   I think mostly release notes really come into play when you're doing an update.

00:00:33   It's the ways in which we communicate to our users that things have changed.

00:00:38   You know, these can range in so many different ways, like from the actual prose you write in terms of how detailed you go, where you put these, if you actually do them at all.

00:00:50   Like I feel like there's a lot of things that are worth kind of unpacking here because it is an interesting opportunity for us to communicate with our customers.

00:01:00   You know, we have the documentation and the things that we write and put together with screenshots in our App Store page is our initial communication with the vast majority of our users.

00:01:11   From that point on, release notes are one of the other venues that we really have to talk to our customers unless you have some kind of messaging system built into your app, which may or may not be a good idea or not.

00:01:25   Like it always drives me crazy when I open an app and it pops up and it says, "Hey, here's everything that's changed."

00:01:30   It's like, right, I don't care. I wanted to use the app, not to read right now.

00:01:35   But still, the things that we submit to the App Store I think is probably a common place for this.

00:01:42   I think release notes are a funny topic now because I think increasingly release notes for most of the most popular apps have become just a one-sentence thing that says, you know, bug fixes and performance improvements.

00:01:57   You can have some very bland, very boring, and I guess in many ways it's fair enough because since John McCain complained to Tim Cook about having to keep updating apps in the App Store and getting rid of that badge,

00:02:15   and then somehow magically the next iOS update we had automatic updating in the background.

00:02:22   But ever since that day, release notes probably are less read and less important in that regard because I imagine a significant proportion of users never ever read the release notes.

00:02:34   They are there as a reference and as something that we have to do, but in practicality they're probably not actually looked at very much.

00:02:41   But I don't know, maybe it's a bit silly, but for me I still look at them as something that is a rare opportunity to try and make a connection with my customers.

00:02:52   And for me increasingly, I used to do the slightly more developer-y, like treating release notes as a change log, something that's more technical, like here's a bulleted list of all the things that I did.

00:03:10   And then more recently I think I've moved over towards viewing my release notes as a letter that I'm writing to my customers.

00:03:17   And in some ways I'll even, usually I'm even having a, signing off with my name in the bottom of it, being like, "Hey, this is what I'm thinking about the app, here's some of the things that I worked on, sincerely Dave."

00:03:30   And viewing it in that approach, and I don't know if that's good or not, but I think release notes can span such a wide range of things, and they also have to encompass so many potentially really awkward situations.

00:03:46   Like as we mentioned a couple episodes ago, if you happen to have to remove a feature that people like, or at least a small group of people like, the release notes is how you mention that to them and how you break that news.

00:03:58   And so how we do that and go about that is probably something that is important to have at least some consideration and care about, to handle it in the most delicate way possible.

00:04:10   Yeah, and I think, you know, in the case of a feature removal, like I guess we'll start here and then we'll get more positive towards the end. In the case of a feature removal, it's important to realize, I'd say two main themes. Number one, as you mentioned, no one reads these. Like, relatively speaking, no one reads these. Like, it's not zero, but it's a low percentage.

00:04:32   Number two, if you change something, like a feature removal, that people are going to be mad about, they're going to be mad regardless of what you say. Many of them are going to email you or tweet you or leave a one-star review without reading your release notes, first of all.

00:04:49   They're just going to be mad and they're going to do that. Many of them are going to read your explanations in some form, but will still be mad and will still tweet the one-star review or, you know, still tweet you or do the one-star review.

00:05:01   And there's only so much you can do. You know, so what you're optimizing for when trying to write good release notes or when trying to explain a feature removal, things like that, what you're optimizing for is not, "Let me make everybody okay with this."

00:05:17   Instead, it's like, you know, "Let me do my best to give a reasonable, sensible summary of what has happened or a reason why things have changed or a list of major things that have changed."

00:05:29   And for the very few people who will read it and the very few people who will actually, like, read it with some consideration or, like, you know, not hate you immediately or not be mad or whatever else, you know, "I'll do my best."

00:05:42   That's all you can really do. So, like, in the case of my feature removal in Overcast where I removed the standalone watch playback in the latest update, that, you know, I have gotten a lot of negative reviews about that, a lot of negative tweets about that.

00:05:56   But I think I did the best job I could of, you know, in the release notes, I said, "Here, sorry I had to remove this feature. For more information, go to this, go to marko.org," and there's a blog post there.

00:06:08   And, you know, in that blog post, I gave the whole story, which I told on this show a few episodes ago, about, you know, here's why I had to change it, I'm sorry, and I hope I can bring it back in the future.

00:06:18   And that's about the best I can do there, you know, like it's, I think there would have been more angry people had I not explained it the way I did, but there's still going to be angry people whenever you change or remove anything.

00:06:31   And so, you just kind of have to be okay with that because, again, this is kind of a best effort but low response and low comprehension medium that you're communicating in.

00:06:41   The thing that's tricky though I find is, so what you did there, your actual detailed explanation went in a different place, in your case, it went on your website.

00:06:52   Like, it's kind of an awkward thing I find, I mean, and I understand why Apple doesn't allow us to have links in our release notes.

00:07:00   Where, I mean, I sort of understand why like you could see it as an avenue for abuse or being problematic but I do kind of wish that they did for these for situations like this where the thing that's awkward there is, I can't, like the number of people who went to the App Store saw the saw your release notes, and then open Safari and remember the URL to type in.

00:07:28   They can't even copy paste it out of there. Like, I mean, you have a short URL but still, like, that barrier is in my mind is so high that it's very unlikely almost anybody did that.

00:07:42   And so, if that's true, which I mean is speculation but my guess is that's a reasonable expectation that very few people did that, beyond the people who read your blog regularly and are like, "Oh, he wrote something about this, let me go and read it."

00:07:58   You know, who knew what Marco.org was beforehand, but for the rest of folks, like, it's a tricky thing where I almost wonder if it's better to try and, you know, concisely boil down that blog post into something that you could put just there in the release notes.

00:08:15   And, you know, this is something that I've gone back and forth on many times myself where usually when I'm doing something like, making a big update in a positive sense, like, "Hey, here's all these great new features," or on the negative sense, "Here's some thing I had to change that you may not like."

00:08:30   I often will write a blog post related to that, but I tend to, in my release notes, just say, "Hey," you know, like, try and turn that, like, the four or five paragraph blog post into a one paragraph explanation because it seems like it's just more likely that people are actually going to read it

00:08:49   and honestly probably have the patience to read it, that it's just, you know, it's unlike, people's attention spans for this type of stuff can get very short very quickly.

00:09:00   And so just trying to be as concise as I can as possible. And then I have the blog post, "Is there a tremendous resource when doing customer support after the fact?"

00:09:10   You know, so in terms of when someone then reaches out and says, "Hey," because the reality is most people are not reading the release notes, like, when you have to remove a feature, which is a good example of where this is probably most tricky.

00:09:21   What often, you know, the customer support request you get is the, "Hey, so I used to use this thing and I can't find it anymore." Like, what happened, right?

00:09:32   From their perspective, they don't even know it's gone. They may just think that it's in a different place or it's moved or they configured something incorrectly.

00:09:40   And in that case, having a blog post or something to point them to and say, "Hey, you know, here's what's--" Unfortunately, we had to remove that and here's a detailed explanation why.

00:09:49   It feels a little bit better, but yeah, it's a weird thing to not be able--because we can't link people directly to those release notes--to do anything kind of like linking or just say like, "Hey, go read this over here." Like, I don't know. In my mind, no one's actually going to do that.

00:10:05   Yeah, and that's why--and part of it is, again, it's like you do what you can. Like, I just said go to marker.org. I didn't give a full URL for a permalink page, which I'm helped here of my infrequency of blogging.

00:10:20   It's going to be the top post for a while probably, and if it isn't the top post, it'll be like the second post down or the third post down for the whole time this version is likely to be in the store probably.

00:10:31   So, you know, I'm helped out there, but also, you know, I feel like, again, it's like so few people read that that I don't think is really a problem worth optimizing too much for.

00:10:41   Like, I gave a short version. I gave a short explanation in the description. I said like, "Sorry, I had to remove Send to Watch due to watchOS changes. Details at marker.org."

00:10:50   Like, that's like--I figure like that's the best I can do because almost no one's reading this to begin with. The few people that do read it are not going to read anything long. So, you know, Brevity is your friend here.

00:11:01   And so, this is simply three bullets, the things I changed in the app, and that's the third one.

00:11:07   And I feel like also you have to consider like when you do a blog post as part of an update, that's really the marketing post. That is the marketing material. If there's going to be any news stories written, if you're lucky enough to have press coverage of your app, that's going to be what people refer to, not the two or three lines you put in the changelog in the app store.

00:11:29   And so, it's partially a different approach. Like, it's a different style of writing you should use in like an announcement post. You should cover different things in different ways just because it's more of a general audience thing.

00:11:42   It is a little important though to also consider the downside of doing the blog post thing is that, again, when you just put it in the changelog, almost no one reads that.

00:11:55   If you make a blog post out of it that people might link to or the press might cover, you draw attention to it. And that could be good or bad. If you're doing a big new version, great, draw attention to it.

00:12:07   If you're removing a feature or doing other like, if you're basically announcing bad news, drawing attention to it might not be what you want. That might be actually a bad idea.

00:12:20   In the case of this feature, I made the decision to do this because I thought it required some explanation about why I had to remove it.

00:12:27   I have removed other smaller features before. Like, there used to be an option called seek acceleration where, you know, as you hit fast forward or rewind in a podcast, more and more, if you hit it like a lot in a short time, it starts jumping by larger intervals because it seems like you're trying to get further.

00:12:45   This used to be optional. It was on by default. I found that almost nobody turned it off and I figured it wasn't even worth having the option anymore. So now it's just always on and I removed the option.

00:12:56   I did that, I don't even remember when, probably six months ago at least. Maybe, probably more. Maybe a year ago. And I didn't announce that anywhere because who cares?

00:13:05   It was a feature that almost no one used. It is a really minor, inconsequential thing. Sorry for the three people who hate it, but they probably stopped using my app already. It's a very minor thing.

00:13:15   And so it wasn't worth writing a huge apologetic blog post saying, "I'm sorry, I've decided to remove this checkbox in the app because I wanted simpler settings and I wanted fewer things to test."

00:13:27   It wasn't worth drawing attention to it that way because that would have been a bunch of negative attention and a lot of people who might be angry about that are people who might not even notice if the option goes away.

00:13:42   So you're taking on additional negativity when you don't need to. Similarly, I had to be very careful when writing this blog post because, again, keep in mind, people don't read things very carefully.

00:13:54   Especially stuff online, but I think probably everywhere. Comprehension is low. And so I had to be very careful when wording this to be very clear about what I was removing.

00:14:07   Because I've learned from past things where I haven't been so clear or things I've tried to announce only on Twitter or in a short form or whatever else.

00:14:14   If you announce that, "Oh, I need to remove this feature. I'm considering removing this feature," half the crazy responses you get are from people who are really mad that you're removing something that you're actually not talking about.

00:14:27   Like, you're talking about something else and either you didn't communicate it properly or they misunderstood or whatever, you know, whoever's fault it was, they didn't get that memo.

00:14:35   And so I wanted to be very careful when writing this to be clear that I'm talking about the "send to watch" feature. And I called it, I kept referring to it as "send to watch," not "standalone watch playback" or "offline watch playback."

00:14:48   Because those could be very easily misunderstood to mean the entire watch app or playback on the phone when you're offline that happens to be controlled by the watch or something like that.

00:14:57   Those could be very, very easily misunderstood. So I very carefully thought about this. I wrote this post weeks before I published it and I was editing it frequently in that time, making it shorter, more concise, more clear.

00:15:10   Because you run such a big risk if you announce some kind of negativity or removal or other things that people don't like, like a change to your business model. You have to be so clear with how you communicate it. Because again, keep in mind, no one's going to read every word you write.

00:15:28   And those who do might be skimming it or might be already mad and maybe not comprehending what you're saying or not focusing too much on the details. So you have to be so overly cautious about how you word things and what you tell people, what you call things.

00:15:43   Because so many people are going to want to jump and be mad on that. And you have to know what triggers to avoid and how to be absolutely clear so that you're not being unnecessarily blamed for the wrong thing even.

00:15:58   We are sponsored this week by Blue Apron, the number one recipe delivery service that has the freshest ingredients. Blue Apron's mission is to make incredible home cooking accessible to everyone and support a more sustainable food system.

00:16:10   They set the highest standards for ingredients and they're building a community of home chefs. For less than $10 per meal, Blue Apron delivers seasonal recipes with fresh, high quality ingredients to make delicious home cooked meals in 40 minutes or less.

00:16:22   Every Blue Apron meal comes with a step by step, easy to follow recipe card and pre-portioned ingredients. They ship the exact amount of each ingredient required for a recipe. So they're reducing food waste.

00:16:32   And Blue Apron's freshness guarantee promises that every ingredient in your delivery arrives ready to cook or they will make it right. We have used Blue Apron here in my home for something like two years now and it's wonderful.

00:16:44   Even before they were sponsored, we were using them. We love it so, so much. We have been better cooks, we've tried all sorts of new foods and honestly, I don't think they want me to say this, but I have tried other recipe delivery services as well.

00:16:57   And I think Blue Apron is by far the best one. There's a reason we keep coming back to it and it's not because they're the more frequent sponsor, it's because they're the best one.

00:17:05   They have the best recipes, I think, by a long shot and they're most consistent with delivery and everything. They're wonderful. So big fans of Blue Apron over here.

00:17:14   And one of the great things about Blue Apron is that there is no weekly commitment. So you don't have to worry about like, "Oh, we travel a lot or maybe every week we can't quite do it every week, but we want it some weeks."

00:17:25   That's fine. You can go into their app and you can just like turn off weeks that you're not going to be there or that you're not going to be able to cook. It's wonderful.

00:17:31   So check out this week's menu and you can get three meals free with your first purchase, including free shipping at BlueApron.com/Radar.

00:17:40   You will love how great it feels and tastes to create incredible home cooked meals with Blue Apron.

00:17:44   So get started today by going to BlueApron.com/Radar and we thank Blue Apron for their support of this show. Blue Apron, a better way to cook.

00:17:52   So one of the things with release notes that I've had to learn over the years is remembering that I am writing my release notes.

00:18:00   Like unless maybe you're making a developer tool, like remember that I'm writing my release notes for a different audience than myself.

00:18:09   And specifically the thing that I've had to make sure that I walk myself back from when I'm writing release notes or doing this kind of launch communication is recognizing the things that

00:18:21   I thought were interesting problems to solve or technical challenges and in the development of the update that I thought were cool from a technical perspective,

00:18:31   but from a user's perspective are not relevant or not interesting or wouldn't make any sense.

00:18:38   And so often, one of the things that I always find so frustrating is when I do this, I spend a lot of time on an update that is doing some big overhaul,

00:18:50   refactoring in the bottom of the app and it's like it's really ended up with what I think is a really elegant, clever solution to a problem.

00:18:58   And I go to write the release notes and I have to remember, I'm not writing this to someone who is also an iOS developer.

00:19:05   I'm writing this to just a general user who doesn't really care that I solved some GCD threading problem with clever uses of semaphores.

00:19:16   That's not something that they're going to care about or understand.

00:19:22   And that can be tough when you spend all this, like you spend like three weeks working on an update and your release notes are actually just kind of like from a user's perspective,

00:19:31   it's like performance improvement, like will crash less often.

00:19:35   Like those kinds of things can be so frustrating because I want to tell it, like I want to tell the world, like, hey, I did all this really cool,

00:19:43   like hard work down below the surface, but from a user's perspective, nothing changed.

00:19:48   You know, like the app just crashes less. Like that's a good improvement, but they're not going to notice that in a tangible way.

00:19:55   And it's also after I remind myself, like I kind of love when I get insights into how other developers, you know, solved tricky technical problems or when they kind of get into the weeds with things.

00:20:08   And I kind of like appreciate it when I see that in release notes, but just because I see that, like if anything, that's a good indication, like, no, no, no, I really need to not take that as a good, as an example of something good

00:20:20   because I'm a very narrow and specific kind of user who, you know, like I said, maybe if you're making a developer tool, you can kind of get into the weeds a bit more,

00:20:30   but for a general purpose, general audience application, it's important to remember that like I'm trying to explain what's happened in a way that will, you know, make this user want to keep using the app,

00:20:42   will bring them back into it if perhaps they haven't, you know, they just happen to be in the app store and see something pop up there that might grab their attention and bring them back into the app.

00:20:53   Like I need to be writing this in an, as accessible of a way as possible. And in some ways I just need to swallow my pride and be okay with the fact that the world may never know about this like really hard problem that I solved

00:21:07   that no one, that never actually, you know, comes above the surface of the application. And like, that's okay. I have to just like accept that and move on and not publish something that is just going to confuse or alienate my users as a result.

00:21:21   Yeah. Oh yeah, definitely. Like by far the most interesting technical things I've ever done in programming in apps were summarized in the release notes as minor fixes and improvements.

00:21:32   That's it. That's all because harsh. Yeah, it is harsh, but like, but I'm, again, you're writing it from their perspective, right? From there, even though for me, I consider it a major improvement or a major fix, but they would consider it minor.

00:21:46   Like if you fix a bug, you don't even need to list which bugs you fix unless there was like some massive crashing bug in the previous version that everyone knew about, you know, otherwise, and in which case you can even say the next version, fix the crashing bug from the last, like, you don't even have to go into details.

00:22:01   Otherwise, when you fix bugs or when you make things better, no one cares. You care, you get satisfaction out of it. You know, developers care. Your users do not care at all and they shouldn't need to care and they never will care no matter what you say.

00:22:14   So best to keep it short fixes and improvements and then, you know, use the rest of your allocated space in that field to talk about some, maybe some new thing that they might care about that, you know, some new feature or new ability in the app.

00:22:27   And if there's one, leave it out. It's fine. It's fine to be brief. You know, there is a place if you want to share technical details. There are ways to do that.

00:22:35   They're called blog posts and this is something that should not even be probably in your marketing blog post. Like if you're going to do a separate blog post for the, for like a major release, I would say this is not a good place to go into technical detail.

00:22:48   If you did something huge, like you converted the whole app to Swift, something like that, maybe submit that that might deserve one sentence in your marketing blog post.

00:22:59   But it certainly does not deserve to even go in the change log in the app store and you know, because like who do your, do your users care if you can work the whole app to Swift? Do users care if the app is now 20% faster?

00:23:11   No. All you can say like converting the entire app to a different programming language to me would qualify as minor fixes and improvements.

00:23:19   Which is, take, take, take some getting used to it. And I think we just, it's like having to just, I think it's, there's a certain humility and just being able to be like, yeah, like that work is just the cost of doing business.

00:23:29   Like that work is not, you don't get like extra brownie points for solving something like that. Like you get brownie points for coming up with interesting features and finding new ways to solve user problems.

00:23:41   But solving technical problems, like that's just table stakes. That's just what the cost is. That's just the bare minimum you have to do. And so you don't get credit for it just for doing something like that.

00:23:51   I think, and then also this should kind of help focus where it's worth allocating your effort and energy during a new product release. It's like, whatever is going to be worth spending your time on are going to be things that users might actually notice and might actually care about and things that might be worthy of user relevant bullet points in that changelog or that marketing blog post.

00:24:15   If you're going to spend a ton of time tackling some, you know, hairy technical problem or converting your app to a different language or switching to a different database layer or something like that, like those are things that are massive time and effort sinks that are going to be worth zero in your marketing.

00:24:34   Like your users are not going to care at all. Your marketing blog posts and the press that you hope will cover them will not care at all. You are like, that's going to get you nowhere. So that's not really worth investing tons of unnecessary time into.

00:24:49   If you have to, for like technical debt reasons, fine, then you have to still shouldn't spend a ton of time on it. If you could help it, sometimes you can't help it, but oh well. But if you're thinking about like, okay, I have to, I have to tackle like these like five big difficult time consuming bullet points on our, on our wishlist here.

00:25:09   We can afford to do maybe two of them for this release. If, if neither one of them is something that's going to be representing, you know, a major thing for your users that you can market and that people will love and care about, it might increase your sales.

00:25:23   I would strongly reconsider your priorities. And so like if you, if you're spending an entire release cycle doing something that's only paying off technical debt or only doing interesting hairy problems behind the scenes that are not representing major improvements for your users, your users are going to have a really hard time getting excited about that or justifying paying for an upgrade or things like that.

00:25:46   Yeah. And I think that's just the reality we have to deal with. Like it's, it's in some ways it's, it's kind of like I almost wonder if in some ways it's a good, it would be a constructive exercise to write the release notes for the update before you do the technical work to do the update.

00:26:04   As it just is, at the very least as a thought exercise to try and understand how is this like how rather than sitting down at the like at the very low technical like level, like looking at it from the other end, I mean like I can put in this work, what is that going to end up looking like from my customers perspective, what kind of release notes would come out of this update and do it doing that exercise ahead of time may be very constructive as a way to be like, huh, yeah,

00:26:31   that that makes it that takes a bit of the shine off this. If all I'm going to end up with like all the all I get from, you know, all this solving this hard technical problem is, you know, minor improvements.

00:26:43   Exactly. Big app 2.0 minor fixes and improvements. Yeah, that's not very compelling. Exactly. Yeah, like throw some bones to your users like, you know, if you're in the position where you have to, you know, spend a lot of time on technical stuff that you just won't care about.

00:26:59   That's a really good time to also tackle like easy features like a couple new options that maybe in your setting screen that are easy to implement that people have asked for a lot, you know, stuff like that, like easy things like that.

00:27:10   Like, you know, like when I added my three X speed that took very little effort that was mostly just testing to make sure it performed well on slower devices and to make sure it was intelligible at all to anybody with any content, which is tricky.

00:27:22   That was a relatively easy gimme and it was the kind of thing like I had to do a bunch of other technical stuff in these releases. And so I threw that in as kind of like a bone like I needed something easy to, you know, keep people interested and to keep the mood happy and everything else.

00:27:36   So I threw that in, you know, that if you if you're forced to do a lot of technical work and and you you are not going to have a lot to show for it to the users. That's a good time to do features like that.

00:27:46   And last thing I just wanted to mention that I think is a sort of as a personal experience with release notes is that don't be too afraid of like, I don't I don't love super like the cutesy release notes when they get like people are like telling a story from the perspective of the app.

00:28:03   And it's like like this long, like the writing a short story about the update like that's a little far. But don't be afraid of being a little bit fun with it. And usually in my experience, what that comes down to is being a little bit personal, like talking about the story of why the feature came into into existence, or if there's an any kind of interesting human element, like I the re in pedometer plus plus, you get confetti when you hit your goal.

00:28:29   And when you double your goal, you get blue confetti. And when you triple your goal, you get pink. And when you quadruple your goal, you get purple. And the reason there's blue, pink and purple above that is because my kids asked me to add that feature to the app.

00:28:42   And I thought that was kind of fun. And like I put that in the release notes, and I got a lot of really positive feedback from people who kind of like that little insight that like, you know, my son thought that there should be blue confetti, and you should get it when you double your goal.

00:28:54   And like, that's where that feature came from. And like, that's a nice human connection. That was also kind of cool or like being a little bit silly, like once I had a feature where an update where there's a bug in the confetti system, and it wasn't firing all the every time that it was supposed to.

00:29:09   And in my release notes, I said, you know, this, this, this update includes bug fixes to avoid a situation where confetti wouldn't fire when, you know, when you when you should have gotten it as compensation, please accept 10% higher confetti rates from here on out.

00:29:24   And I increased the confetti rate by 10% in the app. And it's like, exactly like it's kind of cute. It's kind of silly. But I think those are the kinds of opportunities where hopefully you can make an actual meaningful connection with a customer.

00:29:35   Because you can maybe you make them laugh, maybe you make them smile. And if you can think of an opportunity to do that, take advantage of it.

00:29:42   Yeah, most people won't read them, but for the few that do, reward them.

00:29:45   Yeah.

00:29:46   All right, we're out of time this week. Thanks for listening, everybody. And we'll talk to you next week.

00:29:50   Bye.