Six Reasons Your App Needs Release Notes

Including release notes for your app is good for business – and, more importantly, not including release notes is bad for business. Here’s why:

Release notes improve reviews

People often read reviews to decide whether they will use your app or service.  Several prominent, respected, quality services (including Uber and Dropbox) started to include their release process (“we release updates regularly”) as their release notes.  Their app review scores plummeted to 2 stars (Dropbox) and 1.5 Stars (Uber) on the App Store. Their apps are fine, their service is fine. The ratings plummeted right after they stopped including release notes. Why?

Think about it: Release notes are in the same place in the App Store as reviews, and reviews reset with each update. So, the people who write reviews are largely the same ones that read release notes. You may say, “apps auto-update and nobody reads release notes”. Think again – power users read release notes. No release notes, no reviews (or negative reviews) from your power users. That means your primary source of reviews is people who want to complain about your app or who are less likely to know how to use it.

Dropbox started including release notes again in January – the app’s now up to 2.5 stars; it’s hard to recover lost users.

Release notes build trust

Release notes tell users what you’re doing, and what you’re installing on their device with each update.  “Bug fixes and improvements” is vague but acceptable.  “We release updates regularly” is evasive and insulting.  Of course you release updates regularly, but what are the updates? 

Good release notes communicate to users that you respect them and want to communicate what you’re installing on their devices.

Non-release notes communicate the opposite: you don’t respect them and don’t care if they know what you’re installing on their devices or not.

Interrupting users is a bad user experience

Apps that don’t include release notes tend to announce new features by opening a screen that requires the user to read and/or dismiss it before using the updated app.  When a user runs your app, they’re trying to do something; That is not the right time to share your new features. What is the right time is when they’re reading through their app updates to see what’s new.

Releasing frequently wastes time

A suite of well-known apps states in their release notes, “we release updates weekly”. Why? You’re not releasing anything important enough for release notes, yet it takes the App Store’s reviewer’s time to check your update, it takes user’s bandwidth and time to download the update, and it takes your power users’ time to read “we release updates weekly” every week.

Release notes improve sales

I’m a power user. People ask me for help and recommendations. Apps that have release notes, especially clever ones, I remember and like more than apps that don’t tell me what they’re updating.  (If they don’t tell me what they’re updating, I assume they’re updating something they don’t want me to know about, or that their development process is so sloppy that they just don’t know what’s in each update).  As a result, I’m far more likely to recommend an app with release notes and to inversely recommend against an app that doesn’t have release notes.

Release notes increase user engagement

Power users, if not all users, read release notes periodically.  These all appear in a convenient list in the Updates section of the App Store (on iOS, not sure about Android).  If users read something interesting in the release notes from an app they haven’t used or have forgotten about, they may open the app to see what’s new.

Conversely, as I’ve written about before, users are likely to delete an app if they’re not using it extensively and see vague statements like “we update our app regularly” as the release notes.

How to develop excellent websites and web applications easily

[UPDATED 5/30/2013 for HTML5/CSS3/Responsive Design]

Developing a great website or web application is really very easy, but there are many ways to do it badly, and that makes it difficult.

Here’s how to do it “right”.

  1. A URI identifies each unique resource
  2. Gather your content, and code it in straight, standard, valid HTML
  3. Lay out your content using CSS using responsive design techniques.
  4. Ignore the flashy new technology, stick with well-established basics
  5. Get the user’s language from the Accept-Language header.

These 4 simple rules are all you need to design great sites. Companies are constantly trying to push their fancy new technologies, and browser makers put proprietary features into their browsers hoping you’ll use them, and force people to use their browser. Unfortunately, this just makes your site unusable to people not using that browser.

A URI identifies each unique resource

URI means “Unique Resource Identifier”. Originally, and sometimes still, this meant that a unique string identified each page on a server. It’s a great, simple concept: any given set of content should have a unique URI (yes, that’s redundant). This blog page has a unique string that identifies it. You can send that string to your friends (hint hint), and if they put it in a web browser, they’ll see this article. Seems straight forward, but many many web sites break this rule. For example, if I’m searching for flights on a travel site and have a certain set of flights displayed, I should be able to copy the URI and send it to my friend. Unfortunately, this rarely works. If I load up my shopping cart with stuff at Amazon.com, I should be able to send that cart to my friend. I can’t.

Make your sites RESTful. That’s a fancy word meaning “use the web the way it’s designed”. The O’Reilly “RESTful Web Services” book is excellent extended reading on this subject:

Restful Web Services

URIs are fancy things that can include a LOT of information. Let’s take the examples I gave above and do them right:

Filtering flights

I see filters on web sites done wrong all the time, and it drives me nuts. It’s so easy to do right, and would be so convenient. I apologize, because now you’ll be driven nuts too.

Each element of a filter should be included in the URI. Let’s say you’re setting up a travel site. People fill in departing and arriving airport, dates, and preferred time range. They click a “search” button. The button should encode that search into a GET request (NOT A POST!), which then displays the result. So it might look like

http://www.mytravelsite.com/flightsearch?dep_loc=lax&arrive_apt=nyc&dep_time=12&dep_date=2011-10-20&ret_date=2011-10-30. (I’ve left a lot of potential detail out, like return time, for brevity).

Say your “flightsearch” page has more filters. It’s really fancy, and clicking a column header sorts by that column. When a user clicks a filter, say selecting a max price of $500 per flight, the URI should change to, say, include “max_price=500”.

http://www.mytravelsite.com/flightsearch?dep_loc=lax&arrive_apt=nyc&dep_time=12&dep_date=2011-10-20&ret_date=2011-10-30&max_price=500

Now we sort by price:

http://www.mytravelsite.com/flightsearch?dep_loc=lax&arrive_apt=nyc&dep_time=12&dep_date=2011-10-20&ret_date=2011-10-30&max_price=500&sort_by=price

Now that’s a nice URI I can email to my friend and say “look at the cool flights to New York, let’s go!”. It’ll have the exact filters I selected and even be sorted the same. This URI represents “Flights from LAX to NYC departing Oct 10, 2011, returning Oct 20, 2011 that cost less than $500 ordered by price”.

Sadly, you’ll see similar results on sites that might include the flight info, but once you start clicking on options like price, time windows, and sorts, those don’t factor into the URI.

Shopping Cart

I’ve never seen this done right, but it’s so easy to do right.

To be RESTful, (and have Unique Resources to Identify), you shouldn’t maintain “state” on the server. That means no session cookies (although I’ll concede to an authentication token, but I’ll get to that later). “But how do I store my user’s shopping cart” you ask? Let’s follow the rule: A shopping cart with certain items in it is a resource. That resource should have a unique identifier. If I go to that identifier (URI) later, I should see the same cart. If I send the URI to my friend, they should see the same cart.

http://www.myshoppingsite.com/cart/myusername

So as I shop and click “add to cart”, my items get POSTed to /cart/myusername. A GET to /cart/myusername returns the items in the cart. Ideally, this would be a basic XML document that gets wrapped with a page layout via an appropriate CSS style sheet (sticking to the content/layout separation rules). That way, you could use it in an API to an iPhone app, or as a mobile web page, or as a normal web page by just using the right style sheet. But we’re not talking about that yet.

From here you might want to let the user set up multiple shopping carts. You could have:

http://www.myshoppingsite.com/cart/myusername/12345

A POST to http://www.myshoppingsite.com/cart/myusername/ now would create a new cart and return its ID (e.g. in the resulting web page). Subsequent pages would then POST to /cart/myusername/12345. The user could then create carts specifically to email to friends, e.g. “here’s a cart of all the stuff you need to build the game PC we were talking about”.

For details on how to formulate RESTful URIs, read that O’Reilly book above. And notice that handy URI that takes you to a page on Amazon.com and tells them I sent you. 😉

I’ve mentioned “GET” and “POST” above. These are HTTP methods. There are four total methods: GET, PUT, DELETE, and POST. These tell a server to GET a resource, PUT (change or replace) it, DELETE it, or add to it (POST). So if we were maintaining a database of products, product number 12345 might be identified by the URI http://www.mysite.com/product/12345. A PUT to this URI would change the product. A DELETE would delete the product. A GET would return the product’s info. You wouldn’t POST to this product. However, to create a new product, you would POST to http://www.mysite.com/product/, which could create a new product and return a new product number for it. You can read all about that in the RESTful Web Services book.

I mention HTTP methods because there’s a sub-rule that’s often broken in web pages: GET should be used to retrieve information, and POST should be used to change it. When you’re writing a web form in HTML, you can specify the method in the “form” tag. If you’re doing a search form, this method should be “GET”. If you’re changing a user’s password, it should be “POST”. HTML doesn’t support PUT or DELETE. If you use the wrong method, you’re hindering your site, and you could end up doing real damage in some cases. For example, if you POST a search form, the user can’t bookmark it and send the results to his friends. That could be (lots of) lost business. If you use GET in a form that adds a new product, you could accidentally hit “back”, and that product would be created again. If you reload the page, it’d be created again and again. What if you did that with a credit card order form? That could be hard to explain. Stick with good URIs, and use GET to get, POST to change, and you’ll make great sites.

Gather your content, and code it in straight, standard, valid XHTML

People often do this step backwards, and it gets confusing. They think they want a site to look cool, so the focus on graphics and/or use a template. That’s like painting a picture before you know what you want to paint.

One thing is true of every single web site: its sole purpose is to get some information to someone. Someone wants something, and a great site gets whatever that is to the user as easily as possible. If your site is a store, the perfect site would read the customer’s mind, charge their card, and ship the item they wanted to them. Your job is to get as close to that as possible.

So when you start designing your site, get your content together before ANYTHING else. If you’re starting a store, gather your inventory and marketing text. If you’re advertising your company’s services, get the info about your company together.

Break the information into chunks that are easy to search and navigate. e.g. on most basic company sites, you’ll have a page of contact/location information, a basic introduction page, a page with more detailed info about the company, and a page about your products or services.

Each chunk becomes a resource, and gets its own URI (for a basic web site, that means each page gets a URI, which is what happens if you put a page on a web server anyway. So you’ll get http://www.mysite.com/about.html, for example.)

The content goes into straight, boring XML or XHTML. No layout information. If I look at it, it should look like a linear outline. This means any device or browser will be able to display it. Or, an iPhone app could read it.

If you find yourself thinking about layout here, stop it. If you output a navigation menu, it should look like a bullet-point list. Use attributes to give classes and IDs to your elements. Then the CSS can use that information to create any layout you want.

Your page output should look something like this:

My Company - About Us

	css" TYPE="text/css" MEDIA=screen>
<ol>
<li><a href="/index.html">Home</a></li>
<li>...</li>
</ol>
<h1>About Us</h1>
We are a company that does stuff and things ...

Notice there’s nothing about layout in there. The navigation information is just in “li” tags, and the content of the page, if displayed without a style sheet, will just look like a boring outline.
The navigation menu, in REST parlance, provides information to the client about available resources based on the request for the current resource. In short, it tells you places you could go from here. The client (e.g. the browser) could choose to display that information, turn it into buttons in an app, or hide it completely.

Once you’ve got your content in HTML, run it through the validator at w3c.org. If you ever find yourself testing in different browsers, or writing JavaScript that checks what browser the user’s using, slap yourself and stop it. The world wide web works on standards – write your code to the standards and it should work on all browsers. The browser’s job is to render a page according to the standards. If it doesn’t, that’s its problem. If developers follow the standards, browsers that don’t follow them will disappear, because users will switch to a browser that works. If you need content in a different format (e.g. XML for your iPhone app), that should appear at a different URL (for example http://api.mysite.com/cart/myusername/). But if you stick to delivering your content straight up in standard HTML, you won’t have to go through the trouble of providing different “views” for it. (btw, by “different format” I mean delivery to APIs and such, NOT different layouts, which I’ll discuss next. As far as your web site/app goes, I should be able to hit the URL from ANY device and it should just work.

Lay out your content using CSS

CSS is magic. It can do incredible things, including making the boring HTML above look like a full-blown web page. You can add background colors and images. You can place things anywhere on the page you want. You can (must) even have the content resize based on the browser window width. You can specify layouts for different media types, including “screen”, “print”, and “speech”. You can change the color of a button when you click on it. You can turn the navigation list above into a tab-like navigation menu that changes colors when you click on each tab. You can anchor the nav bar to the side of the screen while the rest of the page scrolls. Read all about it at w3.org.

The point here is, use CSS to lay out the content. If you want to support a different layout on a small screen than a big one, do it in CSS. You can do this through what’s now called “responsive design” (which we called “dynamic layout” back in 1996, but without “media queries”). Responsive design is very simple: lay out your content so that it moves dynamically instead of sitting like it’s on a piece of paper. There are many great articles on responsive design on the web – a couple of my current favorites are responsive design in 3 steps, 5 Useful CSS Tricks For Responsive Design, and iPhone Website Development. There are also excellent responsive WordPress themes (such as “Responsive”, which I’m using at the time of this posting).

I’d like to say a word about “mobile” sites: some sites provide a subset of their main site’s content for mobile devices. This is stupid. Responsive design helps fight this, but some sites still drop content from the mobile versions even then. Bad. Decide if your information is useful enough to include on your site or not. When you find yourself thinking “well, this page has too much information for a smaller screen”, maybe your page just has too much information. Consider breaking it up into smaller resources, or consider just dropping the “too much” part of the information. Don’t clutter the user’s browser and bandwidth just because it’s there. Again, this goes back to the “gather your content first” rule. If the user just wants to know the time, don’t give them a map of the world along with it. [The fancy phrases for this now are “progressive enhancement” or “mobile first design”.]

Ignore the flashy new technology, stick with well-established basics

This is where most developers run into trouble. Which browser should I code for? What technology should I use? Ooh, Cold Fusion looks cool, JavaScript is cool, this new programming language is cool, .NET looks like it makes things easy, I can write nifty menus in Flash, etc, etc, etc…

There’s always something new and cool. The problem is that most of it doesn’t work well, or doesn’t run on a user’s browser, or breaks the rules above.

Stick with what works and you’ll write great sites that won’t give you headaches: UNIX, Apache, PHP, Python, Perl, MySQL, Postgres, JavaScript, Java. For frameworks, Django, Ruby on Rails, and maybe Cake, Drupal, or JEE6. Stick to those and you’ll be writing great sites that’ll actually work. These technologies also let you stick to the rules above easily (well, Cake, Drupal, and JEE6 might not). Try to use MVC design (look that up on Wikipedia). Avoid flash (use JavaScript instead), Cold Fusion (breaks rules), and anything by Microsoft (breaks rules, isn’t reliable – heck, even their browsers break the rules).

Get the user’s language from the Accept-Language header

The web browser will send a header (Accept-Language) that contains a list of languages, in order of preference, that they’d like to see your page in.  If you’re supporting multiple languages on your site (probably a good idea on the World Wide Web), use this list to determine the language you’re going to serve, NOT some geolocation service.  It’s really annoying for, say, someone from California who is visiting France to visit a popular search engine and have it display in French.  There are also countries in which people speak multiple languages (e.g. the United States, Europe, and most of the rest of the world).  The browser tells you what language it wants – give it to them.  If you are (or your client is) concerned about the user not knowing how to set their language, set up a page that tells them.  You can, in addition, let them select the language on your site to override the browser, but don’t just ignore Accept-Language and use geolocation or a menu selection.  If you don’t have access to the Accept-Language header, you can at least get the browser’s language from Javascript with “var language = window.navigator.userLanguage || window.navigator.language;”.  That’s not optimal though.  See this stack overflow post for some solutions.  Also see the w3c spec and this w3.org post about setting language and locale settings.

A note about REST and sessions

RESTful services don’t store “state” on the server. That means it doesn’t matter what browser I use, where I come from, or how long I wait between requests. On a RESTful site, I could start a flight search on one computer, bookmark my URI, go to another computer, click the bookmark, and keep going. Or, I could start a shopping cart order on one system, email my friend the URI, and have him place the order for me. Of course, this isn’t how sites work. One big issue is “authentication”. In a RESTful web service, there are a few extra components to that URI request: Authentication (who are you?) and Permission (are you allowed to perform this method on this resource?).

So for our shopping cart, my friend would first have to prove to the server who he is, and then he’d have to have Permission to see my cart. It’s the Authentication step that gets tricky. Ideally, the user would prove who he is (usually using a username and password) with every request. Browsers do support this, but it’s not very friendly. This is usually worked around by using session cookies, which is difficult, non-RESTful, and causes annoying problems like taking the user to a page they didn’t request after logging in, forgetting the information in a huge form they entered, etc.

Instead of using cookies, use HTTP Auth Digest. If you want a pretty login form, you can create one with JavaScript. There’s a good article with code samples by Paul James that shows you how.