Book Review – Swift Documentation Markup by Erica Sadun


  • Share on Pinterest

SwiftDocMarkupCover

Erica's new book designed for use with Swift 2.1 and Xcode 7.1 covers documenting code. The book is 96 pages long, and you can find it in the iBooks store.

Xcode now supports the ability to use Markdown, HTML or just plain text. The new documentation system can aid teams in communicating what code does without the tedium of writing documentation afterwards. Because as good developers we all write excellent documentation right? 🙂

“naked code is never quite self-documenting.

Erica Sadun.”

The book covers what structured documentation is, how it works, how you can build it with or without using Markdown, a Markdown cheat sheet, labels, keywords and practical considerations.

Just as I was wrapping up this review, a new update was released that added a section on third party tools and playground markup.

Every section is full of examples that you can play around with in Xcode and indeed within minutes I was noticing ways I could improve my current code documentation.

“You, future you, and your team are first-class consumers of Quick Help comments.

Erica Sadun.”

One of the great things about using the new documentation system is viewing notes in the quick help and tooltips throughout Xcode, this is a big plus for those of us sharing code around teams or returning to old projects many months later.

The chapter on building structured documentation has a comprehensive list of rules to follow for documenting everything from protocols to enums and variables. I would go so far as to suggest thinking this list is a best practices recommendation.

I am a big fan of Markdown, so I was very interested in using it for creating my content. Erica does a great job at explaining how it works and which markdown rules are understood by Xcode, for example, you can include images! There are also detailed notes on how Apple uses the format within their documents with real-world examples from the Swift libraries.

Overall this is an excellent book for getting started with documentation, and as mentioned earlier this is something we should all be doing. I feel the content is well worth the price and a handy reference material for any digital library.

You can find the book on the iBooks store here. I also recommend following Erica on Twitter @EricaSadun.