Issue 370

21^st September 2018

Written by Dave Verwer

Comment

I was watching Max Howell talk about creating brew yesterday at FrenchKit. As part of his presentation, he made a great point about how important it was for open source projects to have great readme files and I couldn’t agree with him more.

As part of putting this newsletter together each week, I read a lot of readme files. As you might imagine, I have opinions on the subject. 😂 Creating a really great readme is hard and it takes more time and care than you might imagine.

Does it start out by saying what the project actually does? You’d be surprised how many don’t! Does it say how it will benefit the potential user? Does it spend more time talking about how to install it than it does saying how it will help you? If the library contains something visible, does it include a screenshot or two? If animation is important, are those screenshots presented as animated gifs? All of these things, and more are important.

As part of the discussion that happened on Twitter, Tim Searle bravely volunteered the readme from his Euclid library for a public critique. Hopefully it was an interesting thread if you want to give it a read.

If you maintain, or help to maintain an open source project, when was the last time you took a look at the readme file from the position of someone completely new to it? Could it be improved? Marketing isn’t just for apps and services, it applies to open source libraries too! 👌

Dave Verwer

Sponsored Link

With our quickstart, you can take a transaction within minutes. Learn how to connect Square hardware to your app for payments.

News

I’m sure you’re all familiar with Swift 4.2 by now, but I wanted to highlight the official post as it is wonderful to see Apple acknowledge the community in it. In this instance, with a link to Ole Begemann’s new 4.2 features playground. This is really great to see!

Oh and if you’re wondering how Swift 5.0 is shaping up so far, Paul Hudson has the jump on that with a post and accompanying playground.

That Apple kept Shortcuts (née Workflow 😀) largely intact for the iOS 12 release is incredible. That it led to them finally acknowledging, and even officially documenting x-callback-url is even more astounding. What a time to be alive! 🎉

Tools

Had you noticed this new feature of the Xcode 10 debugger? Thanks to Thomas Zoechling for pointing it out!

Code

I agree with Ben Scheirman, if you’re new to the language that this language feature could feel weird. However, I think it’s easily explainable and worth the potential confusion for the improvement to the language. I like it.

iOS 12 had some big developer features like ARKit and Create ML, but that’s not what this week’s NSHipster post is about. It’s about the small things that you might otherwise have missed. Did you know you could detect a “flat” device orientation, or read an NFC tag when your app is backgrounded?

As you might imagine, this was nearly the “And Finally…” link fo this week, but I can actually see this being potentially useful in all sorts of projects. As someone who once built an iOS game which allowed user uploaded photos, I wish this had existed several years ago. 😯

I often link to open source apps in the hope that they’ll teach someone something about app development. One disadvantage of linking to a GitHub repository though is that there’s usually not much of a guide about how to get into the code if you’re new to it. Not so with AudioKit Synth because this post will give you a great start at getting into this comprehensive open source audio app.

macOS Development

More links in the macOS category? 🤯 There might be even more next year when Marzipan gets an official release. Until then, here’s Peter Steinberger with a practical look at getting an app up and running using unofficial techniques.

It’s worth mentioning that Marzipan is not officially available to developers in Mojave, and that today’s version will very likely have fundamental changes by the time Apple really let us see it next year. That doesn’t mean this article isn’t worth reading though! 🤓

Design

I agree with every word of this fantastic article from Max Rudberg and Simon Ljungberg on why you should integrate with Siri shortcuts to allow much deeper integration of your app with the operating system.

Peter Livesey with a great article looking at the on boarding experience of one of his own apps. He takes inspiration from the wonderful User Onboarding site and does a run through of the old version, followed by an explanation on how he fixed some of the problems.

And finally...

“Scott, you don’t understand. You know how we pay by swiping your badge and then it’s deducted from your salary? I only get paid a dollar year! Every time I swipe we get a free meal!”

Great stories.