documentation

This is just a quick update to let you know that yes, we know that the Shopify developer documentation needs work. There’s a fair bit of information there, but it could stand some improvement. There’s some missing information, it could be organized better, there are parts of it that are confusing and there need to be examples in languages and frameworks other than Ruby and Rails.

This update is also here to let you know that we’re actively working on it, bit by bit, every day. As I write this, David Underwood and are are working on a wholesale reorganization of the developer sections of the wiki and clear writeups of all the API resources, including explanations of the parameters they expect and the attributes they return as well as how they relate to other resources and what effects they have on shops. We’re also working on more example code, in more languages.

If you’ve got comments, questions and suggestions about the docs or what we’re doing with them, please let us know — feel free to leave a comment or drop me a line.

If you’re thinking about exploring unfamiliar parts of the Microsoft platform and don’t know where to start, try using one of the Developer Guidance Maps. Like city maps, they give you an at-a-glance view of the “lay of the land” and make certain useful “landmarks” – different types of documentation, key topics on developing for a specific technology and notes on features you need to know about – easy to find.

Built by the people at Microsoft’s Connect Innovation Center, they’re using the Developer Guidance Maps as a way to model, prototype and test ways to find, organize and share guidance for developers in a meaningful way. I find them pretty useful, both for myself as well as places to point developers with questions.

The Developer Guidance Maps break down the platform into a number of subject hubs:

Interview with Chris Slemp, MSDN

Here’s another video interview featuring Yours Truly at the PDC: it’s with Chris Slemp, Program Manager for the Server and Tools Online group at Microsoft. In the interview, we talk about MSDN and its new social bookmarking feature.

“Grim Fandango’s” Puzzle Document

If you’re looking to get into the mind of a game designer and the design of one of the most highly-regarded computer adventures games, be sure to check out the Grim Fandango Puzzle Document. Tim Schafer, in “a temporary fit of Cake-induced Grim nostalgia,” decided to put the game’s puzzle design document online in PDF form (it’s 2.3MB in size).

I use that word "crafted" because that’s exactly what this newly released document shows: true craftsmanship. We see the incredible attention to detail, the pacing of the narrative as it builds and as the puzzles get increasingly sophisticated, always coaxing the player along with them. As somebody whose spent the last few years trying to write my own adventure game, what struck me most about this document is the sheer simplicity of it – it’s well established that it takes a great deal of clarity and hard work to boil down something so vast as Grim Fandango into such a simple representation that conveys so much information in such a succinct way.

It’s a considerably more interesting read than most specs.

My Job-Related Reading List

Nothing gives you that frozen-caveman-thawed-in-modern-times feeling like returning to a software platform after not developing in it in seven years. Getting back into the swing of Microsoft’s development tools has been fun so far, but it is, as a lot of people have told me, like drinking from the firehose.

To quickly get acclimated with C#, ASP.NET and XNA, I’m expensing the following books I bought today:

“Zero Punctuation” Reviews

And finally, a couple of reviews from my all-time favourite game reviewer, Ben “Yahtzee” Croshaw. The first one’s for Saints Row 2, which includes a great argument for why it might actually be a better game than Grand Theft Auto IV as well as a brilliant concept for a new game:

and here’s the latest review, for Dead Space, which he summarizes as “competent but bland”. Luckily, his review is anything but…