Archive for the ‘Books’ Category

Updates to Swift Documentation Markup

cover

Just submitted an updated version of Swift Documentation Markup to the iBooks and Leanpub stores. This new version includes revisions to my coverage of the excellent Jazzy documentation tool and new coverage of the VVDocumenter Xcode plugin, which automatically adds documentation templates to your code when you type ///.

Jazzy now supports some markup parsing, including parameters. Compare the output from the new version, shown here:

Screen Shot 2016-01-15 at 11.21.11 AM

with the old output here:Screen Shot 2016-01-15 at 10.09.27 AM

It’s a fantastic and welcome improvement.

The VVDocumenter works by adding documentation templates to any symbol when you type /// (three forward slashes) before its declaration.

Screen Shot 2016-01-15 at 10.20.07 AM

Just fill in the boilerplate with your details. VVDocumenter automatically adds placeholder tokens using <# and #> so they highlight in your source editor.

Note that as with any plug-in, you need to keep VVDocumenter up to date so it works with each revision and beta of Xcode.

Book Review: The Useful Book

Screen Shot 2016-01-13 at 3.40.53 PM

Netgalley recently allowed me access to Sharon and David Bowers’ The Useful Book (Workman Publishing, $20) to see what I made of it.

For someone who holds DIY and “making” close to her heart, it’s a fun but imperfect find, featuring over a hundred practical how-to “skills” that you might not have picked up from traditional sources like Home Economics class or Wood Shop.

The book consists of two sections, one focusing on home skills, the latter on handyman ones. The page layout is easy to follow with sensible columns, lots of art, and simple step-by-step instructions. You can dive into a random page and grab some how-to without having to read from cover-to-cover.

I see this more as a gift book suitable for a coffee table than a much-loved reference. I found the coverage to be entertaining even when I disagreed with some of the suggested approaches or found them missing important details.

I warn you that some of the topics may seem a little underwhelming (“How to boil water” and “How to care for your (sewing) needles” spring to mind). The practical applications (“Superstitious folk wisdom advises that, to protect a child from evil spirits during sleep, a key must be slipped under his or her pillow”) may not exactly fit my corner of the DIY community.

For example, my physicist husband points out that there’s absolutely no reason to stick with cold water for boiled water (#1, “How to Boil Water”), as dissolved mineral danger is hyped up in his opinion. He adds that the reason you want to cover your pot is to prevent heat from escaping, and make your water boil faster, more than losing water content through steam.

I learned that I could have drained my tofu (#47, “How to Cook with Tofu”)  — a step I have never taken and am unlikely to adopt even now, but was happy to learn about. (I use my hand to provide top-down pressure as I slice tofu sideways first before doing rows and columns.)

We like bright lights in our workspaces and are unlikely to swap them out for cost-saving lower wattage units (#177 “How to Slash Your Electricity Bill”)

This isn’t to say there isn’t good advice on-hand, like sanding rough spots when patching a wall but I do wish that they’d offered advice like checking the inside of a bike tire as well as looking at the outside for possible reasons why it went flat, a critical tip in goathead country.

If you’re looking for a nice housewarming gift for a new couple, this title could suit the bill. If you’re looking for a deeply geeky read, this probably isn’t going to be your cup of tea.

Sorting and sharing playground pages

Sorting Playground Pages

If you keep a lot of playgrounds on hand in a single file (I do!), you may find it handy to sort your pages alphabetically. Use Edit > Sort > By Name to clean up your organization.

Screen Shot 2016-01-04 at 10.07.27 AM

Hopefully you’ve named each page logically, for quicker scanning.

Screen Shot 2016-01-04 at 10.08.16 AM

Unfortunately, as you add pages to playgrounds, Xcode performance takes a massive hit. While you can re-order by dragging, that starts to become impractical once you hit a couple of dozen playgrounds.

Copying Playground Pages

It can be simpler just to drag copies of a page into a new workspace with better performance. This screenshot shows dragging the “adding arrays” page over to a new playground file.

Screen Shot 2016-01-04 at 10.18.15 AM

You can also open a playground package (Control-Click/Right-Click > Show Package Contents) and access individual source files however you like.

Screen Shot 2016-01-04 at 10.22.04 AM

You cannot drag and drop these between packages unless you’re willing to start editing the contents.xcplayground XML. It’s not difficult, but it’s generally not worth your time.

Instead, consider opening the page in a text editor, and using copy/paste into a new page you manually add to another playground.

Searching Playgrounds

Xcode offers two search fields to help you locate material. The bottom search bar matches page names:

Screen Shot 2016-01-04 at 10.15.09 AM

The search at the top of the navigator finds matching text.

Screen Shot 2016-01-04 at 10.13.47 AM

Searching Playgrounds from the Command Line

A while back, I wrote pggrep to find playground files, which were not otherwise indexed by spotlight. Given how much material ends up in playground testbeds, pggrep has been a valuable tool for finding where I had explored some topic or another in the past.

Book

There’s also a book on all things Playground.

Updated linter

Just updated my testlint project (http://github.com/erica/testlint) to start searching for Swift 3.0 issues. For example, SE-0003 will remove var parameters. So this will no longer compile:

 if var testStream = OutputStream(path: aPath) {
     print("Testing custom output", toStream: &testStream)
     print("Hello ", terminator: "", toStream: &testStream)
     print("World", toStream: &testStream)
     print("Output sent to \(testStream.path)")
 } else {
     print("Failed to create custom output")
 }

Instead, you’ll need to use if-let and create a var inside the success branch.

if let outputStream = OutputStream(path: aPath) {
    var outputStream = outputStream
    print("Testing custom output", toStream: &outputStream)
    print("Hello ", terminator: "", toStream: &outputStream)
    print("World", toStream: &outputStream)
    print("Output sent to \(outputStream.path)")
} else {
    print("Failed to create custom output")
}

My linter started off as a complete hack, in response to SwiftLint‘s minimal beginnings. I kept working on the repo because (1) I had complete control over it and (2) it offered many more rules that I found valuable. It’s still a complete hack but it’s evolved into a way I can explore style rules in preparation for writing Swift Style.

It is still not a great linter (it goes line by line instead of parsing because I didn’t want to use inter-process hacking and it relies on regex, waving my hands, chicken entrails, etc). However, it’s been an amazing way to start thinking about the way I do and should write Swift.

I think you’d probably get more out of my comments in Linter.m than via daily use. Just thought I’d let you know that it was updated.

Status: Another Swift proposal in the works, Swift Docs book update

Matthew Johnson was kind enough to let me pitch in on a proposal he was working on to make Standard Library protocol naming more consistent. Here is the updated proposal we put together. It would be great if you could read through it and share your thoughts on twitter with me (@ericasadun) and Matthew (@anandabits).

This is my third big Swift tweak suggestion, which can best be explained by the fact that I’m so busy with kids until January that I can barely get any “real” work done. (By the way, I just pushed an update to Swift Docs to iTunes and Lean Pub. Big thanks to Juan Diego for errata feedback!)

The first (discarding C-style for-loops) recently was accepted for 3.0. The second is now a bug report feature request but started off as a standard proposal. I’ve also poked my nose into suggestions about documenting the overall proposal process a few times.

I have an ever increasing stack of notes for my Cookbook update and for Swift Style. Both will have to wait until school starts again for the kids.

Stepping into the light: Swift’s new public evolution

Yesterday, I wondered whether we’d have early access to all Swift updates. Could we take it as a given that the entirety of language development would now be open? Would we, outside of specific dev-tool enhancements, transparently see the full progression of incorporated, proposed, and planned changes through the Swift evolution list, the Apple Github repo, and the swift.org site?

“The Swift team will be developing completely in the open on GitHub,” Federighi told Ars Technica in a write-up by Andrew Cunningham. “As they’re working day-to-day and making modifications to the language, including their work on Swift 3.0, all of that is going to be happening out in the open on GitHub.”

Cunningham writes, “So instead of getting a big Swift 3.0 info dump at WWDC 2016 in the summer and then digging into the Xcode betas and adapting, developers can already find an “evolution document” on the Swift site that maps out where the language is headed in its next major version.”

As a tech writer who was counting on this, I have now let out a big sigh of relief.

The complete Ars Technica post is here.

Black Friday, Cyber Monday: Buy my books, save some money at InformIT

According to my InformIT sources, the Swift Developer’s Cookbook preorder is 35% off on Black Friday Week. Coupon Code: BF2015. If you pick up Gourmet at the same time,  you save 55% off the pair. (Sun 22 Nov – Sat Nov 28).

On Digital Monday, you can pick up my ebooks (“digital products”) for 55% off, using the Coupon Code: CM2015 (Sunday 29 Nov – Mon 30 Nov)

Read the fine print for details or ping @InformIT on Twitter if you have any questions.

Swift Developer’s Cookbook: Status Update (Mark December 17 on your calendars!)

41XD0j6+b5L._SX388_BO1,204,203,200_

Checking in on the Swift Developer’s Cookbook:

  • The book has finished production. It’s available for pre-order at Amazon. InformIT has a pre-order page up as well.
  • It’s available right now to read at Safari Books Online through their Rough Cuts program. You can get a free multi-day trial.
  • The book will participate in Pearson/Addison Wesley’s new Content Update Program, which I describe below in this post.
  • My editor says the actual pub date is December 17. It will make an awesome holiday present for yourself or your favorite geek.

What’s in it?

The cookbook kicks off with a discussion of how to migrate code when the language changes. (Some persons I showed this to inside Fruit-world were dismayed: “Why are you starting off with migration?” Everyone outside Fruit-world I showed this to nodded their heads with wry understanding.)

Within the book, each chapter focuses on day-to-day-development concepts and best practices. This is the book you buy after working through Apple’s language tour, to learn how to use all those language features to get real work done. You can view a full table of contents at InformIT in the Sample Content tab.

I’m hoping this book will work for both Apple-centric Swift developers as well as new developers jumping in from Linux after the big Open Source event.

The Content Update program

My Pearson team and I spent a lot of time discussing how to develop content for a language that’s been changing since it launched. While I think Swift 2 is going to be a lot more stable than Swift 1, I wanted to be sure we accounted for Apple’s constant, accelerated tech changes.

The Swift cookbook participates in Pearson’s new Content Update program, which works like this:

  • As Apple makes significant updates to the Swift 2 language, sections of my book may be updated or new sections added.
  • Book updates are delivered via a free Web Edition, which can be accessed with any Internet connection.
  • Customers register their books (print versions, ebook versions, whatever) with AW/Pearson, and if and when content changes, they receive email updates.

In other words, the CU program acts a guard against the book going out of date two days after you purchase it. What’s more, I architected the book to be as long-lived as possible, focusing on core language concepts.

So, to wrap up, thank you everyone who has pre-ordered and thank you everyone who’s considering a purchase soon. If you have any specific questions about the program or the book, drop me an email.

 

If this book existed, would you buy it? (Part 2 in a series)

Remember my poll about a possible Swift Markup book? Based on your feedback and support, I went ahead and wrote it; Swift Documentation Markup is now at iTunes and from Leanpub. Thank you everyone!

So, next, how about this?

Style

Would you buy a book about common Swift style rules? Something similar to the topics I brought up yesterday in this related post but more comprehensive, with discussion and code samples? Keep in mind this wouldn’t be a bible — just helpful, hopefully well sourced, opinions and suggestions.

A few things:

  • If there’s anything specific you’d like to see in a book or any issues you have with the ideas I throw out in my posts, please ping me and let me know.
  • Now that I’m set up over at Leanpub, I’m intrigued by their system of installment-publishing. iBooks also supports updates, revisions, and expansions. Would you be more interested in a whole-book-at-once or reading-as-I-write in general?

And finally, these are the existing books in my self-published series:

Screen Shot 2015-10-14 at 3.08.34 PM  cover