{ "version": "https://jsonfeed.org/version/1", "title": "Allen Pike", "home_page_url": "https://www.allenpike.com/", "feed_url": "https://www.allenpike.com/feed.json", "author": { "name": "Allen Pike" }, "items": [ { "id": "/2019/making-a-list-bold", "url": "https://www.allenpike.com/2019/making-a-list-bold", "title": "Making a List, Bolding It Twice", "date_published": "2019-04-30T21:10:10+00:00", "content_html": "

Writing is meant for reading.

\n\n

Sometimes, the reading doesn’t matter that much. We might dash off a quick text, toss out a laugh line, or send a rote confirmation. Our emoji are leaves on the wind.

\n\n

Other times though, the reading matters a lot. Occasionally we need to write something that must be understood, absorbed, and acted on. The more important it is that readers understand and act, the more time you should spend refining the writing.

\n\n

There are a lot of things you can do to make an email, blog post, proposal, or process document clearer. For example you can keep it short, make it engaging, or have a colleague refine it before sending it out. These can all help a lot.

\n\n

However, if it’s critical to you that your writing is read – especially by busy people – you need to make it skimmable.

\n\n

\n\n

There are a few ways you can facilitate this.

\n\n

You can use short sentences and paragraphs, for example. That helps a lot because folks tend to primarily read the beginning of each paragraph. It’s kind of a hack, but it works.

\n\n

There is one core approach though, one workhorse of the skimmable document, that is worth mastering: lists. Lists are rightly derided in the era of Buzzfeed, but the same principles that drive engagement on social media also drive engagement in a Google Doc or email. So today, I’d like to share one weird trick to quickly writing a clear and useful list: The Bolding Trick.

\n\n

The Bolding Trick

\n\n
    \n
  1. Draft a bulleted list, whether it’s the key goals for a process, the main principles in a design, or whatever. Rather than trying to make it perfect on the first go, just get it out.
  2. \n
  3. Your list should only have 3-8 items on it, with each item 1-3 sentences, which should keep it readable and digestible. Still, unless each item is extremely short, the resulting block of text can still be a slog to read, appearing monotonous and causing your audience’s eyes to glaze over, or – worse – cause them to decide to read it later.
  4. \n
  5. For each point in your list, find and bold the key phrase in the paragraph. For example, the key phrase in this point was “bold the key phrase”. This will make the list far more skimmable.
  6. \n
  7. If it’s an important list, it’s worth also pulling those bolded phrases up front. Once the core points are bolded, run down the list again and pull the bolded part to the beginning of each item, making it the heading/summary of the item.
  8. \n
  9. Your eminently readable and skimmable list is now ready to be absorbed and acted upon, and easily maintained.
  10. \n
\n\n

A thing I love about this process is that when you pull out the key phrases into headings, it also naturally drives you to edit the prose to be clearer:

\n\n

The Refined List

\n\n
    \n
  1. Make a bulleted list. Hammer out the key goals for a process, the main principles in a design, or your weird trick for making lists.
  2. \n
  3. Include 3-8 Items. Make the list clear and focused by keeping it to 3-8 items of 1-3 sentences each.
  4. \n
  5. Bold each key phrase. Go through the items you wrote and mark in bold the 1-4 words that matter most. This would be often be a verb phrase in a process document, or an adjective phrase in a list of goals.
  6. \n
  7. Make the phrases headings. While you can stop after bolding, it’s often worth also pulling the key phrases into inline headings. Rewriting your list this way also helps you refine and repeat the key points.
  8. \n
  9. Share and maintain. The formatting will make your list much easier to read, update, and act on.
  10. \n
\n\n

I find this approach faster than trying to come up with the headings first, and it has the added bonus of being incremental: after each pass you can stop and you have a useful document.

\n\n
\n\n

Once upon a time, when I would try to document a process or a project, I’d approach it like a blog post. I’d spin a narrative, write pages worth of context and detail, and really get to the heart of the matter. Once the resulting tome was complete, it would be read once, and then left to the sands of time. That was fine for battle stories and manifestos, but not so much for process or design documents.

\n\n

Now, I write short docs consisting mostly of lists and bolded key phrases. They get read and maintained.

\n\n

It’s a lot better.

\n\n" },{ "id": "/2019/information-needed", "url": "https://www.allenpike.com/2019/information-needed", "title": "Information Needed", "date_published": "2019-03-31T21:10:10+00:00", "content_html": "

If you publish apps for iOS, understanding the App Store review process is part of your job. While the core guidelines are public, their enforcement relies on a large set of private rules and policies, policed by human beings. When you’re trying to release an update to your customers, the keeper of the Bridge of Death is not the nicely summarized guidelines, but the machinery that enforces them.

\n\n

\n\n

The high-level guidelines don’t change often, and when they do change developers are often warned in advance. The enforcement policies though – the de facto rules – are continually mutating in response to the latest App Store scams, PR issues, or problem areas.

\n\n

So, while some guidelines – such as the one about not sending push notifications for marketing – don’t seem to be enforced at all, others are strictly enforced to the letter of the law, and flouting them will prompt a swift rejection. Or, more nerve-wracking, an eventual rejection of a bugfix update that doesn’t change the relevant functionality. So it helps to know the system.

\n\n

You say you wanna add subscriptions

\n

For example, suppose you’ve seen where the wind is blowing, and have decided to add subscriptions to your app. In preparation, you may come across public Guideline 3.1.2:

\n\n
\n

Ensure you clearly communicate the requirements described in Schedule 2 of the Apple Developer Program License Agreement, found in Agreements, Tax, and Banking.

\n
\n\n

While you probably should read the full agreement, it’s a little over 24,000 words long. Maybe more of a weekend read. In the meantime, you can save a bit of time by scoping out a little thing I like to call the “Apple Developer Program License Agreement Schedule 2 section 3.8 part b”.

\n\n

This clause actually has some pretty clear language asking developers to:

\n\n
\n

…clearly and conspicuously disclose to users the following information regarding Your auto-renewing subscription:

\n \n
\n\n

Presented with the above, any app designer worth their salt will have a follow-up question: is it even possible to design a nice subscription flow that actually makes all eight of these things clear and conspicuous? Even with all the detail Apple provides – more than we generally get with most guidelines – the requirements leave key questions about how they’ll actually be enforced:

\n\n
    \n
  1. Do the App Store reviewers require text meet a certain standard to consider it “clear and conspicuous”? (They do.)
  2. \n
  3. Do the links to your privacy policy and terms of use in your app’s settings count towards this requirement? (They don’t.)
  4. \n
  5. Do reviewers require that some of these things are more clear and conspicuous than others? (They do.)
  6. \n
  7. Would they approve an app that followed Apple’s own examples of how to implement subscriptions? (Not even close.)
  8. \n
\n\n

I know about these pitfalls thanks to various developers sharing their lessons learned about the unwritten parts of Apple’s subscription guidelines. As thanks, I wanted to pitch in by sharing some info about a different guideline I’ve learned a fair bit about over the years: 2.1.

\n\n

Guideline 2.1: Information Needed

\n

According to Apple’s data, the most common reason for an app to be rejected is ostensibly a simple one: “Guideline 2.1 – App Completeness”. The public guidelines for 2.1 describe a few kinds of incomplete or trivial apps, for example:

\n\n
\n

We will reject incomplete app bundles and binaries that crash or exhibit obvious technical problems.

\n
\n\n

Eminently reasonable. In addition to this though, App Review categorizes a common type of provisional rejection as being under Guideline 2.1: “Information Needed”. Since an Information Needed rejection is usually unexpected, it can easily ruin a developer’s day. Thus, it helps to be prepared.

\n\n

Here are some common reasons you may hit a 2.1:

\n\n
    \n
  1. You didn’t include a working demo account. D’oh.
  2. \n
  3. You didn’t include enough info to test your In App Purchases. This is apparently quite common – reviewers have to try out your IAPs, and if it’s not immediately clear how to do so you can get a 2.1 rejection.
  4. \n
  5. Your app is sketchy. Certain categories of apps are, by volume, often scam or spam. Slots apps, for example, can get a 2.1 as basically a “one strike warning” to give the developer a chance to double-check whether they violate certain rules before they go through full app review. There are various copies of this warning text online, so if you’re participating in the dodgy end of the App Store then it’s worth being aware of this.
  6. \n
  7. Your app isn’t testable on a simulator. If your app isn’t testable except in the “real world”, or requires special hardware, reviewers may 2.1 reject the app pending a video that shows how it works. If your app doesn’t run in the simulator, pre-prepping a demo video can help expedite this process. Steamclock builds a lot of apps for Bluetooth devices, so we prep these fairly often.
  8. \n
  9. You need to prove that your company is authorized to offer this app. For example, let’s say you titled your app “Royal Bank of Canada”, but tried to publish it under “Surprised Pikachu LLC”. You may be surprised when App Review asks for some evidence that you are in fact the largest financial institution in Canada and not in fact a lazy scammer.
  10. \n
\n\n

While these cases are all fairly straightforward, there is one particular 2.1 request that I have seen from time to time that did surprise me when I first saw it, and as far as I can tell not much has been written about it. You may in fact be rejected if:

\n\n
    \n
  1. Your app requires users to log in, but doesn’t offer account creation.
  2. \n
\n\n

Without a way to create an account, App Review can’t evaluate your payment mechanism. In this case, App Review will typically hit the brakes to determine if the app violates “3.1 Payments”.

\n\n

If your app’s business model was crafted specifically to circumvent Apple’s In App Purchase rules and you thought just not offering in-app account creation would be enough to fool them, then you’re gonna have a bad time. Otherwise, things aren’t so bad. You just need to – carefully, but quickly since your app update is now in the dreaded Review Limbo – make the case that your business model is kosher.

\n\n

One of the few accounts online of this process comes from this Japanese blog post by Takuya Matsuyama, who outlines what App Review may ask in this “business model review” scenario:

\n\n
\n \n
\n\n

Through the magic of Google Translate, I can see that Takuya and I felt similarly after getting this kind of rejection for the first time:

\n\n
\n

Even though Apple’s examination was nothing last time, it is scary because it is pointed out from the point of view not to predict suddenly.

\n
\n\n

Put another away, it’s not fun to have the Supreme Gatekeeper suddenly audit your business model.

\n\n

Being prepared

\n\n

Since I know better than to try to end-run around Apple’s payment rules, every time I’ve received this kind of rejection I’ve been able to walk App Review through the business model and why it’s above board.

\n\n

That’s not to say caution isn’t merited. I’ve definitely seen clients get a business model review, respond ambiguously without understanding the underlying guidelines, and as a result get caught in a slow secondary review. Don’t be like them – be prepared.

\n\n

If you’re considering building an iOS app that requires login but doesn’t let users create accounts in-app, be sure to review and understand Apple’s rules around in-app payment, and schedule an extra 1-2 weeks when you launch or make a major change to the app to accommodate a potentially long review. If your initial submission is approved without a 2.1, be cautious since any future update, even a critical bugfix, could trigger the review.

\n\n

If the bridgekeeper perceives your iOS app to be main value of a service customers are paying for elsewhere, they could toss you into the Gorge of Eternal Peril for not offering IAP.

\n\n

If everything is on the level though, and you just haven’t gotten around to providing account creation in-app in your initial release, then you should be fine.

\n\n

Just don’t forget your favourite colour.

\n\n" },{ "id": "/2019/podcast-episode-numbers", "url": "https://www.allenpike.com/2019/podcast-episode-numbers", "title": "325: Podcast Episode Numbers", "date_published": "2019-02-28T21:10:10+00:00", "content_html": "

In iOS 11, Apple made a variety of changes and improvements to the Apple Podcasts app and spec. Among other things, they added support for a new show format: serial podcasts. Finally, narrative-driven shows could request to be shown in strict chronological order.

\n\n

As part of this change, Apple added support for an “episode number” tag, and recommended that podcasters stop including episode numbers directly in the title of each episode. Sure whatever, metadata best practices blah blah.

\n\n

Smash cut to yesterday, when we all received a mass email from Apple Podcasts about ensuring our show isn’t “rejected or removed from Apple Podcasts” by “optimizing your show’s metadata”. While much of it was just about not being spammy, they asked more firmly this time for podcasters to stop including episode numbers in titles:

\n\n
\n

Adding episode numbers in titles. For example, show titles like “The Very Hungry Tourists Episode 01” or episode titles like “01 Broken Heirloom.”

\n
\n\n

I was a bit surprised by this. Everybody includes episode numbers in their titles… don’t they? Though come to think of it, why do we? Why do I do it for Fun Fact? We don’t number our blog posts; why podcasts? Am I being sucked into a deeply pedantic rabbit hole, never to return?

\n\n

No, why, why do you care about this Allen

\n\n

According to historians, podcasters have included episode numbers in titles since the late Cretaceous Period. There are a few benefits, but the primary two are:

\n\n
    \n
  1. Give people an easy handle to find or refer back to to a specific episode
  2. \n
  3. Make it easier to play through episodes from the beginning in a podcast client
  4. \n
\n\n

While the introduction of “serial” shows has made playing from the beginning easy for certain kinds of podcasts, apps still make the assumption that all shows are either strictly linear and need to be listened to in order (a crime investigation in 10 parts), or that each episode is completely unrelated and you would never want to start from the beginning (a daily news briefing).

\n\n

This is a pain in the ass for shows where the episodes are loosely ordered, kind of like a sitcom. The episodes make sense on their own, so new viewers probably want to check out the latest one first – but there are back-references and follow-up items that can make it appealing to listen from the beginning. Without episode numbers, this can be annoying to actually do.

\n\n

In an ideal world, Apple would support a third type of show, something like episodic-series, for shows where playing from either end is desirable. It could then prioritize the newest episodes, but still surface episode numbers and accommodate users who want to start at the beginning.

\n\n

Back in the actual world, Apple wants you to decide if your show is linear or ephemeral, and stop trying to hedge that classification.

\n\n

Still though, why do they care? Is it truly awful to have semi-episodic podcasts putting numbers in their episode titles?

\n\n

As is often the case, you can indeed find something truly awful by exploring iTunes:

\n\n

\n\n

Yes that’s right, on the desktop iTunes will number your numbered episodes as if the latest episode was episode 1, followed mind-bendingly by the episode number you’ve included in the title. While this is horrific, it actually makes podcasters want to keep including their episode numbers right in the title, since otherwise the presentation makes it look like the newest episode was actually your first, which is even more horrific and I just can’t even with this thing.

\n\n

Thankfully, most people do not listen to podcasts in desktop iTunes. The big show, the app that we – and Apple – are concerned about is Podcasts on iOS. So let’s take a look at how episode numbers show up there.

\n\n

045: The Why Do You Care About This Allen Show – Ne…

\n\n

With iOS 11 and the new metadata, Apple built accommodations for episode numbers into the UI, allowing them to cleanly and consistently show numbers in contexts where it matters – such as serial shows – and not show episode numbers in contexts where it doesn’t matter. For an example, let’s take a look at the Top Episodes list.

\n\n

\n\n

Now, £1 says that Jony Ive would be rather cross if he saw this list with 5 different formats for showing episode numbers. With title data this noxious, there’s not much Apple can do to present a nice, clear list of episodes.

\n\n

Consistency aside, in this context the episode numbers aren’t even useful. While the Top Episodes list should in theory be a gentle entry point for somebody new to podcasting, it is currently weird and intimidating.

\n\n

If they can get podcasters to provide title and episode number metadata separately, Apple Podcasts can show the numbers where relevant, and style the them thoughtfully in different contexts, rather than being forced to serve up the the dog’s breakfast that is episode title metadata today.

\n\n

And while numbers in titles is a time-honoured tradition, I have to admit that episodes of newer shows that follow Apple’s guidelines look pretty nice amongst their metadata-laden peers.

\n\n

\n\n

The more I look at these screenshots, the more sympathetic I am to the ideal of relegating the episode numbers to metadata, and having player apps take the responsibility of showing those numbers where they’re useful. In fact, when it comes to finding specific episodes or playing “episodic” shows chronologically, modern podcast apps already have some helpful features that make episode numbers less important than they once were.

\n\n

For example, in Overcast you can tell a smart playlist to sort by “Oldest to Newest by Podcast”. Then, if you go into a show’s back catalog and add a horde of early episodes, they’ll automatically stay together in chronological order. It’s pretty hidden, but in Castro you can also queue up a show chronologically by subscribing to a show, then going to Library → That Show, then dragging “All” to your queue.

\n\n

While neither of these approaches are as nice as a simple UI for playing a show from the beginning, I think they can bridge the gap if shows start to move episode numbers into metadata and players get smarter about it.

\n\n

Similarly with episode discovery, instead of scrolling to find a numbered show, you can type an episode title into Apple Podcasts and it will come right up. In Overcast you need to search for the show first and then the episode title, but the functionality is still there.

\n\n

Unfortunately, there is still a gap between the web and podcast players when it comes to linking an episode. As far as I know, there’s no way yet for your podcast’s website to predict the URL for “Open Episode X in Player Y”, which would make it easier to go from a Google search or a shownotes link right to listening to an episode. With luck this will come.

\n\n

I get it, you care, what are you going to do about it

\n\n

Regardless of what any 3rd party podcast apps are doing, the reality is that Apple runs the biggest podcast directory and app in the world. They’ve told us to give them a clean title and episode tag in <itunes:title> and <itunes:episode>. In return, they’ll be more likely to feature our show, Jony will be placated, and they’ll stop maybe-implying that our podcast may be “rejected or removed”. So, a pretty easy call there, I think.

\n\n

A more interesting question remains though: for semi-episodic shows like Fun Fact where people may want to start at the beginning, should we keep the episode number in the <title> tag for 3rd party clients like Overcast and Castro? Certainly some people with opinions on the internet think so.

\n\n

But I have to admit: I can’t unsee what I’ve seen. I’ve beheld the clean and clear presentation of numberless episode titles. I’ve heard from the listeners who are scared off from trying out podcasts where every title advertises how many episodes they’ve missed. I’ve come to terms with the fact that for our show – even a few months in – starting with the most recent episode is the way to go. And most dangerously of all, I’ve come to the conclusion that It Would Be Nice™ if podcast players directly used the episode meta tag to only show numbers where it matters.

\n\n

So, as of today, our episode titles are clean and number-free. It was difficult and emotionally taxing, but I have made peace with my decision.

\n\n

May the the era of clean podcast titles one day come to pass.

\n\n
\n\n

Update: Apple just sent a followup email clarifying that “Your Show Won’t Be Removed for Having Episode Numbers in Episode Titles”. It then goes on to say:

\n\n
\n

We encourage you to use the tag to send us your episode numbers. If you decide to include episode numbers in your episode

\n
\n\n

The email then ends mid-sentence. We can only speculate on the fate of the Apple Podcasts employee who attempted to send this missive. Our thoughts are with their family tonight.

\n" } ] }
https://allenpike.com/feed.json
allenpike.com
crawl=CC-MAIN-2019-22
27781
application/http; msgtype=response
sha1:YUA34JDPUHNB42MHOSS3LTBJ7CIDHWII
<urn:uuid:01297967-765b-4d4d-a0dc-36f917fe2dd4>
2019-05-20T23:08:23Z
142.93.122.177
application/json
sha1:B3BDABMQTUUPH37JKWKR4UUGZXHJJCZH
<urn:uuid:9ccf8cb0-a889-4754-baff-63f3f0ad27a4>
https://allenpike.com/feed.json
response
<urn:uuid:f0329636-de3a-47ff-bf68-d43ae509c421>
isPartOf: CC-MAIN-2019-22
publisher: Common Crawl
description: Wide crawl of the web for May 2019
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-236-17-239.ec2.internal
software: Apache Nutch 1.15 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.1-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: http://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/