documentation

Your Faithful Scribes are Working Away at Fixing the Docs

by Joey deVilla on December 13, 2011

Woodcutting of a scribe working on a text, with the thought bubble "WTF?"

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.

This article also appears in the Shopify Technology Blog.

{ 0 comments }

Microsoft’s Developer Guidance Maps

by Joey deVilla on September 26, 2010

Developer Guidance Maps: photo of a paper city map

When I took this developer evangelism job and returned to the Microsoft platform almost two years ago (after an eight-year hiatus) one of the first things I had to deal with was the sheer size of it. Even people who’ve been working in a certain area of the platform get lost when they venture out to other parts (say, when a desktop developer decides to give web development a try).

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:

You can also choose to cruise the Developer Guidance Maps by technology:

And you can also go through them via resource type:

Give the Developer Guidance Maps a look!

For more information, see:

This article also appears in Canadian Developer Connection.

{ 0 comments }

Salmagundi for Friday, November 7th, 2008

by Joey deVilla on November 7, 2008

Interview with Chris Slemp, MSDN

joey_devilla_chris_slemp

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.

Click here to watch the video.

“Grim Fandango’s” Puzzle Document

grim_fandango_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).

Here’s a great summary of the Grim Fandango Puzzle Document, written by Andy Geers:

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.

reading_list_nov_2008

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

I’ll let you know what I think of these books as I read them.

“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…

{ 0 comments }