I’m testing the waters for the first time in using Github rather than Dropbox to coordinate a private project. I’ve used private repos before for material that wasn’t meant for public consumption or to stage material that would then later be released openly but this is the first time I’m testing it out for material that’s substantially not code.
I’ve been meaning to give this a go ever since Github changed its policy to allow unlimited private repositories. I used to be limited to just five in total and I guarded those slots carefully. Under the new policy, I have repos to burn. Today was the first time that I set one up to use in this way.
It feels odd using Github instead of Dropbox as I’m so used to my Github content being primarily open, and Dropbox requiring explicit permissions. Have you tried using Github this way? And how have your experiences been?
The reason I’m testing out Github is that I’m updating iOS Drawing for Swift. I have a week or so to burn while I’m waiting on editorial feedback and tech review on my Swift Style title from Pragmatic. It will take another 4-6 weeks for Addison Wesley to release iOS Drawing rights back to me but I figured I’d get a head start writing some test chapters and get some early feedback about the project while I had some downtime.
I’ve used Dropbox for years to provide material to beta readers and gather their feedback as well as to coordinate material on multiple machines. In testing out Github, I was inspired by Pragmatic’s workflow.
Pragmatic uses a delightfully retro SVN version controlled interactions between editors and authors. (I’ve had to create an SVN/git cheatsheet to remind myself how to SVN all the things.) Pearson/AW in contrast uses Basecamp to manage projects. Basecamp offers a lot of great team features including messaging, calendars, email updates, and so forth, and I’ve been quite happy with it.
Book projects tend to be hefty, especially those with lots of illustrations and sample code but Github has generous file policies. It imposes a 1GB repo limit, 50 MB file warnings, and 100MB file limits. These are far beyond what I’d need.
I’ve recently changed my overall personal workflow, having been inspired by conversations with editors at O’Reilly. O’Reilly has been pioneering modern, flexible content using markup source. I took my lead from them. (I’m personally using CommonMark instead of AsciiDoc and pandoc instead of Atlas, but the ideas are similar.)
Pandoc has been a pure delight. Even if CommonMark offers less nuance and control than Microsoft Word (however ugly MS Word is, it has power and all the ugly but practical features you need for professional publishing), pandoc allows me to push from manuscript to book in seconds.
I don’t have to use Calibre to build epub, pdf, and mobi output. My code examples are readable and my tables of contents are perfect. I’ve written a bunch of command-line utilities that automate the process of building the ebooks, zipping up archives, and storing copies in a Dropbox beta folder. I still use Dropbox to provide early reader access.
I built Swift Style‘s first draft using this workflow, writing in MacDown, an open source macOS Markdown editor. I like MacDown’s side-by-side display but, to be honest, for material of any size, it has no way to keep the text and output in sync, especially once you introduce illustrations.
If I find some time, I’ll probably try to mess with the source to add this functionality because once you drop the ability to see your edits as you add them, the utility loses a lot of its charm but that’s a project for another day.
In the meantime, I’m just getting settled into Github for this project. A lot of my work steps are similar: I start by pulling and wrap up by pushing but now it’s to the repo, and not to Dropbox. Github offers more version control than Dropbox’s undelete functionality and I don’t have the same worries about filling up my quota.
I’m curious: Are you using Github for non-coding projects? And how has that worked out for you? Did the DNS incident a few days ago make you rethink? Or are you committed to this kind of collaborative tool? Let me know. Thanks!
I finished the first draft today. It’s about 160 pages long, which is a bit longer than I expected. I’ll be revising and tweaking coverage next. If there are any specific style issues you want me to research and/or address please let me know now.
Also, if you’ve purchased any of my self-published titles, please make sure you have the latest versions. The current revision is always listed in the first section with the legal stuff and “Distributed worldwide by Erica Sadun”. The current versions are:
If you do not have the right version, check for available downloads in iTunes or download the latest version from Leanpub.
Here’s the current Table of Contents for the book. If you noticed, I’m using a brand new toolchain for writing so I’ve got a much better ToC than I have had in the previous “Swift. Slowly.” titles:
Good news: There should be an updated version of Playground Secrets awaiting iBooks customers. Apple is looking into why my updates over the summer did not get relayed to customers. This issue does not affect anyone who bought from LeanPub.
Expect another Playground Secrets update soon beyond this. I’m still tweaking to the final Xcode/Swift 3 release. Look for revision 3.5 to debut shortly. It will have “Swift 3, Xcode 8” at the very top.
Good news: I’m also updating Documentation Markup. A preview of some of the changes I address is here. I’m probably going to include at least some of the points I made in my essay about past you and future you.
Good news: The response to the Swift Celebration Bundle has been so strong that I’m extending the sale until at least the end of this week. Thank you everyone!
Bad news: Some nice Xcode features have gone away. Remember this, which picked up information from the structured markup?
It’s now gone. Xcode no longer shows the abstract for the selected match.
Badder news: Xcode fuzzy completion is so relaxed and shows so much stuff that it can be really hard to find the API you actually want. There can be literally dozens of pages of completions for certain APIs.
Good news: After months of going back and forth with Bluehost technical support, they seem to have finally found something slowing down responsiveness. Hopefully this site will be slightly zippier. Not promising great responsive time but there should be fewer 504 errors and database errors and timeouts.
Helpful non-news: Make sure you check your iTunes Connect account to review your old applications. Not all notices are getting sent about the 30-day “you must update this old app” period. If you have some older titles, take some time to check on them.
Helpful extremely non-news: For whatever reasons, you must adhere to standard iTunes Connect dimensions when uploading Book screenshots. The books side of things won’t tell you what they are, but they are: 1024×768, 1024×748, 768×1024, 768×1004, 2048×1536, 2048×1496, 1536×2048, 1536×2008.
Now that I’ve gotten Swift 2 to 3 ready and out, I’ve turned my attention to Swift Documentation Markup. I’m updating the book with both Swift 3 examples and markup enhancements. Xcode has added some great new features although as you’ll see there’s still work left to be done.
Xcode’s automatic doc-comment skeleton command is super handy. Move the cursor to any symbol and select Editor > Structure > Add Documentation (Command-Option-/). Xcode scans the symbol you’ve chosen and adds a doc-comment outline including named parameters and return types if they exist.
You may want to add further comment features like notes, warnings, authorship, dates, and complexity details, but the basics provided by Xcode form a great place to get started.
One Xcode feature that’s just launching is support for treating closure parameters as first-class documentation elements. Xcode’s default documentation doesn’t include closure parameters, as you see in the screenshot that follows.
Swift’s new “no labels for function types” means that many developers will not include the internal declaration arguments that I use in this example for the
By adding internal arguments like
(_ line: String), you can extend your documentation. Xcode picks up and formats that information into a special closure parameter box, subordinate to the closure that uses that parameter. Here’s an example that extends the code documentation you just saw:
Swift’s native comment schema suggests that Xcode could potentially add further support. The schema includes nesting parameters, return values, and throws document comments, as promised in this commit:
As far as I can tell, the only feature that is currently supported by Xcode is the named closure parameters, demonstrated above. Here’s what the schema looks like from Swift’s point of view:
<!-- In general, template parameters with whitespace discussion should not be emitted, unless direction is explicitly specified. Schema might be more strict here. --> <choice> <element name="ClosureParameter"> <optional> <ref name="Abstract" /> </optional> <optional> <ref name="Parameters" /> </optional> <optional> <ref name="ResultDiscussion" /> </optional> <optional> <ref name="ThrowsDiscussion" /> </optional> <optional> <ref name="Discussion" /> </optional> </element> <element name="Discussion"> <ref name="BlockContent" /> </element> </choice>
Unadopted Swift enhancements don’t end there. There’s further work to be done to support changes provided by Swift but not picked up on by Xcode. Here are examples from the Swift language change log and from Swift proposal SE-0111:
- Three new doc comment fields, namely
- recommendedover:, allow Swift users to cooperate with code completion engine to deliver more effective code completion results. The
- keyword:field specifies concepts that are not fully manifested in declaration names.
- recommended:indicates other declarations are preferred to the one decorated; to the contrary,
- recommendedover:indicates the decorated declaration is preferred to those declarations whose names are specified.
- This proposal introduces two new document comment fields,
NonmutatingCounterpart. These replace the roles of the former
messagearguments. Under this scheme,
@discardableResultwill not use arguments. Documentation comment fields will, instead, supply usage recommendations in both directions.
Swift 3 is a major, breaking language change. Are you ready to make the jump? Let “Swift from Two to Three” help you along the way. From migrating your code, updating your style, and adopting new Swift features, this book ushers you into the newly refreshed language. Learn what changed, why it changed, and how you can update your code using this hands-on guide that covers all the major difference with plenty of examples and insight.
Sending a sincere thank you to everyone who helps support my blogging and independent writing by purchasing books.
I’m getting close to wrapping up my latest little self-published Swift book. Like Playground Secrets and Documentation Markup, the book will be available on iTunes and LeanPub. It’s written for anyone who has stayed in Swift 2.3 so they could keep shipping code but who now is looking to move towards Swift 3.
Here are some sample pages to give you a feel for what’s coming up.
As always, if you have any feedback or requests, please let me know. Does this sound like a book you might purchase? I’d love to hear from you.
Thanks again for all the support you give me, my blog, and my books. It’s appreciated beyond measure.
If you like good, stupid, subversive humor (and who among us does not?), consider pre-ordering Jim Benton‘s “Man, I Hate Cursive”.
Due out this October, this cartoon collection for “People and Advanced Bears” is silly, witty, and laugh-out-loud fun. It offers a collection of Benton’s more popular strips from Reddit, “shining a light on talking animals, relationships, fart jokes, and death” according to the book’s promo copy.
I liked it a lot. Admittedly, some of the humor leans off-color: it’s the kind of book you gift a friend, a fellow programmer, a geek, but not maybe your mom unless your mom is a friendly programmer geek, in which case, she’ll enjoy the laughs.
You’ll probably like it too, in which case, it’s excellent for leaving around on coffee tables if you’re a little uptight or in bathrooms, where its humor might be more appreciated during those deeply philosophical times when you forget your iPad and don’t subscribe to the Ikea catalog.
At just under a hundred pages, the book ended way too soon for me. “Man, I Hate Cursive” is available for pre-order on Amazon ($11.07 paperback, $9.99) and will be published on October 18, 2016.
NetGalley provided me with a free copy of the book for this review.
I’m pleased to announce that the Swift Developer’s Cookbook content update has gone live. My editor writes:
Hi Erica,The Web Edition has been updated and is live (I just registered my book and checked it). To access the Web Edition, anyone who purchases the book can just register it at Informit.com. After doing so, the Web Edition will show up on the Account page.You can feel free to post a blog entry, tweet, et cetera that the first update is live.Thanks,Trina
Pearson’s Content Update Program is brand new. It has experienced significant challenges over the past months: floods in Chennai followed by a massive downsizing at Pearson, which caught the CUP point people in the layoffs. With luck, further updates will not take so long. It’s a very weird time to be in the technical writing business.
If you’ve purchased a copy of the book from any vendor, you should be able to register it with InformIT and receive access to the refreshed material. If you have any difficulties, ping @InformIT on Twitter.