Under the Radar

Under the Radar 94: Release Notes


  welcome to under the radar of show about

  independent iOS app development I'm mark

  Worman and I'm David Smith under the

  radar is never longer than 30 minutes so

  let's get started so today we wanted to

  talk about release notes and I guess

  more generally about kind of like launch

  communication strategies and approaches

  oh so around talking about the podcast

  release notes to the conference release

  notes we're actually talking about

  release notes what about the actual

  things that you write and publish when

  you release an update to your

  application or you launch it initially I

  think mostly release notes really come

  into play when you're doing an update

  it's the ways in which we communicate to

  our users that things have changed you

  know these can range in so many

  different ways like from the actual

  prose you write in terms of the how

  details you go where you put these if

  you actually do them at all like I feel

  like there's a lot of things that are

  worth kind of unpacking here because it

  is a interesting opportunity for us to

  communicate with our customers 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 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 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

  it's like right I don't care I wanted to

  use the app not to read right now but

  still like the things that we submit to

  the app store I think is probably is is

  a common place for this 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 you can have ism very bland

  very boring and I mean I guess in many

  ways it's fair enough because since the

  since was it Johnny was John McCain

  complained to Tim Cook about having to

  keep updated up updating apps in the App

  Store and have getting

  that badge and then somehow magically

  the next Ellis iOS update we had

  automatic up updating in the background

  but ever since that day at least 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

  you know there they are there as a as a

  reference and it's something that we

  have to do but in in practicality

  they're probably not actually looked at

  very much but I don't know maybe it's

  maybe it's a bit silly but for me I

  still look at them as something that is

  a a rare opportunity to try and make a

  connection with my customers and for me

  increasingly I've started to I used to

  do the kind of like slightly more

  developer II like more like treating

  release notes as a change log you know

  something that's like I'm something more

  technical like this is here's all the

  like a bulleted list of all the things

  that I did and then more recently I

  think I've moved over towards viewing my

  release notes as like a letter that I'm

  writing to my customers and in some ways

  I'll even you know it's like I'm usually

  I'm even still I having a you know

  signing off with my name and the bottom

  of it being like hey you know this is

  what I'm this is what I'm thinking about

  the app here's some of the things that I

  worked on you know sex sincerely Dave

  like and viewing it in that reproach and

  I don't know if that's good or not but

  it's you know I think release notes can

  span such a wide range of things and

  they also have to encompass so many like

  like potentially really awkward

  situations like if you have to like as

  we mentioned in 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 and so how we do do

  that and go about that is probably

  something that tenure is important to

  have at least some consideration and

  care about to do you handle it in the

  most sort of delicate way possible yeah

  and I think you know in the case of a

  feature removal like I guess we'll start

  here 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 rel

  speaking no one reads like it's not zero

  but it's it's a it's a low percentage

  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 they're

  just going to be mad and they're gonna

  do that many of them are going to read

  your explanations in some form but will

  still be mad and we'll still tweet the

  one start review or you know suite you

  or do the one-star review and there's

  there's only so much you can do you know

  so what you're what you're optimizing

  for when trying to write good release

  notes so we're trying to explain a

  feature removal things like that what

  you're optimizing for is not let me make

  everybody okay with this 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 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

  but that's all you can really do so like

  in the case of my of my future move on

  overcast where I remove the the

  standalone watch play back and let

  analyze update that you know I've gotten

  a lot of negative reviews about that a

  lot of negative tweets about that but I

  think I did the best job I could of you

  know in in the release notes I said here

  this sorry I had to remove this feature

  for more information go to go to this go

  to market org and there's a blog post

  there and you know so and in that blog

  post I gave the whole story which I told

  him 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 and that's about the best

  I can do there you know it's I think

  there would have been more angry people

  had I not explained it the way I did but

  they're still gonna be angry people

  whenever you change or remove anything

  and so you just kind of have to be okay

  with that because again this is good

  this is kind of a a best-effort but low

  low response and low comprehension

  medium that you're communicating

  yeah the thing that's tricky though I

  find is AK so what you did there where

  you you your actual detailed explanation

  went in a different place in your case

  went on your website 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 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 note that had

  the number of people who went to the App

  Store saw the saw your release notes and

  then open Safari and remembered the URL

  to type in that you'd like they can't

  even copy/paste it out of there like

  they I mean you have a short URL but

  it's still like it's that lap barrier is

  in my mind is so high that it's very

  unlikely almost anybody did that that

  and so if you have if that's true which

  means it's speculation but my guess is

  that's reason a reasonable expectation

  that very few people did that beyond the

  people who read your blog regularly and

  are like oh heroes who wrote something

  about this let me go and and read it you

  know who knew what marker 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

  you know couldn't boil down that blog

  post into something that you could put

  just there and there release notes and

  you know this isn't it I've I've gone

  back and forth on many times myself

  where usually when I'm doing something

  like any any making it 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 those I often will

  write a blog post or related to that but

  I tend to in my release notes just say

  hey you know I could turn to try and

  turn that like the four or five

  paragraph blog post into you a one

  paragraph explanation because it seems

  like it's just more likely that act that

  people are actually going to read it and

  honestly probably have the patience to

  read it that it's just you know it's

  it's unlike I

  people's attention spans for this type

  of stuff you can get very short very

  quickly and so just trying to be as

  concise as I can as possible and then I

  have the blog post is there is a

  tremendous resource when doing customer

  support after the fact you know so in

  terms of waiting someone then reaches

  out and says hey cuz the reality is most

  people couldn't reading the release

  notes like when you have to remove a

  feature as I guess which is a good

  example of where this is probably most

  tricky the what it will often the 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 what

  happened right there's 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 and in

  that case having a blog post or

  something to point them to and say hey

  you know here's what's unfortunately had

  to remove that and here's a detailed

  explanation why it's like it feels a

  little bit better but yeah it's a 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 yeah and and that's why you know

  and part of it is again it's like you

  know you do what you can like I just

  said go to marker that org I didn't give

  a full URL for like a permalink page

  which I helped here of my in frequency

  of vlogging this is like it's going to

  be the top post for a while probably and

  and if it isn't the top post it'll be

  like the second post damn it the third

  post down for you know the whole time

  this version is likely to be in the

  store probably yeah 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 it's really

  a problem worth optimizing too much for

  like I gave a short version I gave a

  short explanation in in the in the

  description I said like sorry I had to

  remove send to watch you to watch OS

  changes details at market org like

  that's I figure like that's the best I

  can do because I 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 brevity is your

  friend here and so it's this is simply

  three bullets the things I changed in

  the app and that's the third one so and

  I feel like also you have to consider


  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 gonna be any news stories

  written if you're lucky enough to have

  press coverage of your app that's gonna

  be what people refer to not the two or

  three lines you put in the changelog in

  the App Store and so it's it's partially

  a different approach like it's a

  different style of writing you should

  use in like in like an announcement post

  you should cover different things in

  different ways just because it's it's

  more of a general audience thing it is a

  little important though to also consider

  the the downside of doing the blog post

  thing is that again when you just put it

  in the changelog almost no one reads

  that if you make a blog post out of it

  that you 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 if you're removing

  a feature that is or do another or like

  if you're basically announcing bad news

  drawing attention to it might not be

  what you want it that might be actually

  a bad idea

  in the case of this feature I I made the

  decision to do this because I thought it

  required some explanation about why I

  had to remove it I have removed other

  smaller features before like there used

  to be an option called seek acceleration

  where you know as you as you hit

  fast-forward everyone in a podcast more

  and more if you hit it like a lot in a

  short time it starts jumping by larger

  intervals cuz it seem like you're trying

  to get further 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

  I did that how do you 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 like it was it was a feature

  that almost no one used it is a really

  minor inconsequential thing sorry for

  like the three people who hate it but

  you know they probably stopped using my

  app already you know it's a very minor

  thing 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 be

  is I you know I wanted simpler settings

  and I wanted the fewer things to test

  and everything it it wasn't worth

  drawing attention to it that way because

  that was that would be that would have

  been a bunch of negative attention and a

  lot of people who who might be angry

  about that are people who might not even

  notice if the option goes away it's like

  you're kind of like you're taking on

  additional negativity when you don't

  need to similarly I like I had to be

  very careful when we are in this blog

  post because again keep in mind people

  don't read things very carefully

  especially stuff on online but I think

  probably everywhere comprehension is low

  and so I was I had to be very careful

  when when wording this to be very clear

  about what I was removing so I've

  learned from past things where I haven't

  been so clear or you know things I've

  tried to announce like only on Twitter

  and a short form or whatever else if you

  announce that like oh I need to remove

  this page for I'm considering moving

  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 like

  that 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 and so I

  wanted to be very careful in writing

  this to be clear that I'm talking about

  these send to watch feature and I called

  it I kept referring to it I send to

  watch not standalone watch playback or

  offline watch playback 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 like this could be

  very very easily misunderstood so I

  carefully thought about it I've wrote

  this post weeks before I published it

  and I was editing it frequently that's

  making it shorter more concise more

  clear because it's you run such a big

  risk if you announce some kind of

  negativity or removal or like other

  things that people don't like late like

  a change to your business model you have

  to be so clear with how you communicate

  it because again keep keeping my no

  one's going to read every word you write

  and those who do might be skimming it or

  might be already mad and maybe then not

  comprehending what you're saying or not

  focusing too much on the details so like


  to be so overly cautious about how you

  word things and what you tell people

  what you call things because so many

  people are going to want to jump and be

  mad on that and you have to know kind of

  like what triggers to avoid and and how

  to be absolutely clear so that you're

  not being unnecessarily blamed for the

  wrong thing even we our sponsor this

  week by blue apron the number one recipe

  delivery service that has the freshest

  ingredients blue aprons mission is to

  make incredible home cooking accessible

  to everyone and support a more

  sustainable food system they set the

  highest standards for ingredients and

  they're building a community of home

  chefs for less than ten dollars per meal

  blue apron delivers seasonal recipes

  with fresh high-quality ingredients to

  make delicious home-cooked meals in 40

  minutes or less every blue apron meal

  comes with a step-by-step easy to follow

  a recipe card and pre-portioned

  ingredients they ship the exact amount

  of each ingredient required for a recipe

  so they're reducing food waste and blue

  aprons freshness guarantee promises that

  every ingredient 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 even before they were

  responsive 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 and I think

  blue apron is by far the best one like

  there's a reason we keep going back to

  it and it's not because they're the more

  frequent sponsor it's because they're

  the best one they have the best recipes

  I think it but by a longshot and they're

  their most consistent with delivery and

  everything that they're wonderful so big

  fans of blue apron over here and the one

  of the things with 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 we can't quite do it every week

  but we want in some weeks 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

  gonna be able to cook it's wonderful so

  check out this week's menu and you can

  get three meals free with your first

  purchase including free shipping at blue

  apron calm slash radar you will love how

  great it feels and tastes to create

  incredible home-cooked meals with blue

  apron so get started today if I go into

  blue apron comm slash radar and we thank

  blue apron for their support of this

  show blue apron a better way to cook so

  one of the thing with release notes that

  and I've had to learn over the years is

  remembering that I am writing my release

  notes like unless maybe you're unless

  you're making a developer tool like

  remember that I'm writing my release

  notes for a different audience than

  myself and specifically the thing that

  I've had to make sure that I walk walk

  myself back from when I'm writing

  release notes or doing this kind of

  launch communication is recognizing the

  things that 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 but from a user's

  perspective are not relevant or not

  interesting or wouldn't make any sense

  and so often it's like I like one of the

  things that was draw like how if I'm so

  frustrating is when I do this like I

  spent a lot of time on an update that is

  doing some big you know overhaul

  refactoring in the bottom of the app and

  it's like it's really you know ended up

  with what I think is a really elegant

  clever solution to a problem 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 I'm writing

  this to just a general user who doesn't

  really care that I solved some you know

  GCD threading problem with Morse you

  know with with clever uses of semaphores

  like that's not something that they're

  going to care about or understand and

  that can be tough when you spend all

  this thick you spend like three weeks

  working on an update and your release

  notes are actually just kind of from

  this user's perspective it's like

  performance improvement like will crash

  less often like those kinds of things

  can be so frustrating because like I

  want to tell it like I want to tell the

  world like hey I wrote I did all this

  really cool like hard work down below

  the surface but from a user's

  perspective nothing changed you know

  like the app just crashes less like

  that's a good improvement but they're

  not four they're not going to notice

  that in a tangible way and you know it's

  also after my myself like I kind of love

  when I get insights into how other


  you know solved trick tricky technical

  problems or when they kind of get into

  the weeds with things 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 I really need to not take

  that as a good as a example of something

  good because I'm a very narrow and

  specific kind of user who you know we

  like that maybe if you're making a

  developer tool you can kind of get into

  the weeds a bit more 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 make

  this user want to keep using the app

  well bringing 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 like I need to be writing this

  in and 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 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 you know publish something that is

  just gonna confuse or alienate my users

  as a result yeah oh yeah it's definitely

  like by far the most interesting

  technical things I've ever done in

  programming it in apps were summarized

  in the release notes as minor fixes and

  improvements yeah it is harsh but like

  but I'm gonna 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 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 and the previous

  version that everyone knew about you

  know otherwise and an image case you

  couldn't even say the next version fix

  the crashing bug for the last you don't

  even have to go into details 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 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 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

  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 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 but it certainly does not

  deserve to even go in the changelog in

  the app store and you know because like

  who dear do your users care if you

  convert the whole app to Swift do users

  care if the app is now 20% faster no all

  you can say like converting the entire

  app to a different programming language

  to me would qualify as minor fixes and

  improvements which is take these things

  I'm getting used to and I think we just

  it's like having to just and I guess

  there's a certain humility and just

  being able to be like yeah like that

  work is just the cost of doing business

  like that work is not you don't get like

  poor 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 but solving technical

  problems like that's just table stakes

  that's just what the costs are 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 I think and

  then also this should kind of help focus

  where it's worth allocating your effort

  and energy during ordering a new you

  know new product release yeah

  it's is it like whatever your whatever

  is going to be worth spending your time

  on are gonna be things that users might

  actually notice and might actually care

  about and things that might be worthy of

  user relevant to bullet points in that

  change Locker in that marketing blog

  post if you're gonna 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

  syncs that are going to be worth zero in

  your marketing it like your users are

  not gonna 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 gonna get you nowhere so

  that's not really worth investing tons

  of unnecessary time into 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 you know these like five big

  difficult time-consuming bullet points

  on our on our wish list here 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 mark it and that

  people will love and care about it might

  increase your sales 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 gonna have a really hard time

  getting excited about that or justifying

  paying for an upgrade or things like

  that 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 as it just is you at

  the very least has a thought exercise to

  try and understand how is this like it

  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 doing that exercise ahead of

  time it may be very constructive as a

  way to be like huh yeah that that makes

  it that takes a bit of the the shine off

  this if all I'm gonna end up with like

  all I get from you know all this solving

  this hard technical problem is you know

  minor improvements exact

  big app 2.0 minor fixes and improvements

  yeah that has not very compelling

  exactly yeah I like throw some bones

  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 yours won't care about that's a

  really good time to also tackle like

  easy features like a couple new options

  that maybe a nurse in your settings

  screen that are easy to implement that

  people have asked for a lot you know

  stuff like that like easy things like

  that like you know like I when I added

  my 3x speed that took very little effort

  that was mostly good testing to make

  sure it performed well on on slower

  devices and to make sure it was

  intelligible at all to anybody with any

  content which is tricky but that that

  was a relatively easy

  gimmie 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 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 the

  last thing I just wanted to mention that

  I think it's just a serve as a personal

  experience with release notes is that

  don't be too afraid of like 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

  and it's this like like this long should

  like the writing a little 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 then Luigi in

  my experience what thats comes down to

  is being a little bit personal like

  talking about the story of why the

  feature came into k into existence or if

  there's an any kind of interesting human

  element like i the rienne pedometer plus

  plus you get confetti when you hit your


  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 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're double your goal and

  like that's where that feature came from

  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 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 and in my release notes

  I said you know this but this this

  update is it includes bug fixes to avoid

  a situation where confetti wouldn't fire

  when you know when you should have

  gotten it as compensation please accept

  10% higher confetti rates from here on

  out and I increase 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 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 yeah most people won't read them but

  for the few that do reward them yeah

  alright we're out of time this week

  thanks for listening everybody and we'll

  talk to you next week bye