Terrence Dorsey

Writer. Editor. Nerd.

Toolbox - An Update on Windows Azure Tools

My February column is up over at Visual Studio Magazine and it includes 43 Great Windows Azure Development Resources . I hope you find it helpful.

A lot has happened since I wrote my first Windows Azure Development Resources column for MSDN Magazine back in 2010. The Azure team is doing great work and they should be proud.

#

Updating the Reading List

Quick note to mention that I'm updating my Reading List page from using Amazon affiliate links to instead linking up reviews or other relevant discussion.

Two reasons for this:

First, I'm a proponent of supporting local, independent booksellers and I feel that directing readers to Amazon undermines that.

Second, the Amazon links were a convenient way to direct readers to book summaries and reviews. The affiliate links were a "bonus," but one that never actually paid off. So why bother? There are other sources of more useful reviews. (For example, check out the 1937 review of The Hobbit by C.S. Lewis!)

Replacing older links will be an ongoing project, so check back in occasionally for new book recommendations as well as new review links.

Happy reading!

#

Teaching Programming with Human Functions

Today, in my RubyStory class, I attempted to introduce the kids to Ruby functions. I won't go so far as to say it was a disaster, but it didn't go particularly well. They just didn't get it.

OK. Functions are a pretty big concept for a new programmer to grasp.

I also made a major mistake: too much talking, not enough coding. The kids are much happier and seem to understand better when actually writing code, making things happen and experimenting on their own.

I did experiment with a different kind of example, however, and it seemed to bring some fun and understanding: "human functions." Basically, the kids became functions and we interactively ran the program by talking to each other. Here's how it worked.

First, I took one of the students, Sophie, aside and gave her some secret instructions: "Take the word you're given and use it in a sentence."

Then, one of the other students would "call" her with a word: "Sophie: donuts." Sophie would respond "I love to eat donuts."

We had some fun with it, as 10 year old kids will, and changed up the examples a bit. As I explained, this pretty much equates to the following code.

def sophie(word)
    puts "I love to eat " + word
end

sophie("donuts")

This seemed to help the kids understand a lot better. I think next class we'll start out with more exercises like this before moving to the code. We could get multiple human functions involved to demonstrate how functions generalize tasks within a program.

For example, here's a simplified version of our storytelling program.

def prompt(choice1, choice2)
    print "Which do you choose (%s or %s): " % [choice_1, choice_2]
    answer = gets.chomp
    return answer
end

def story
    puts "A zombie appears. Do you run or fight?"
    action = prompt("run", "fight")

    if action == "run"
        puts "Chicken! Bawk bawk bawk!"
    elsif action == "fight"
        winorlose
    end
end

def winorlose
    puts "Rolling the dice..."
    diceroll = 1 + rand(6)

    if diceroll > 3
        puts "Yay! You win!"
    else
        puts "Sorry, you lose."
    end
end

My human functions can run this program.

  1. Kendall starts the story, and passes the the prompt to Arden.
  2. Arden asks Teddy the question and returns his answer to Kendall.
  3. Kendall either ends the story ("run") or calls Sophie ("fight").
  4. Sophie rolls a die and, depending on the roll, tells Teddy whether he won or lost.

We'll have to see how it works. Looks like I've got a bit of writing and scheming to do before the next lesson.

#

Teaching Kids Programming With RubyStory

TL;DR version: I wrote some course materials and sample code for teaching the basics of Ruby programming to middle-school kids. The course is called RubyStory and teaches just enough Ruby to create a choose-your-own-adventure style storytelling game.

RubyStory


Last year my older daughter started fifth grade and brought home a school-supplied MacBook. Which is great. I think it's important to give kids a chance at an early head start to develop technology and programming skills — an early taste, anyway, to see if they like it — particularly the girls.

I set about looking for an appropriate learning resource to teach my daughter. There's a lot out there. Unfortunately, none of it quite appealed to my preferences.

I wanted something easy for me to read, parse out what was being taught, and know what to pass on to students. Many of the course materials I reviewed required a lot of up-front reading, then I'd have to create my own teaching notes.

Adults and older children might be motivated to learn programming for its own sake, but I think younger kids (8-13 at least) don't have the same motivation (exceptions discussed below).

Learning while doing something fun, however, seems to work. So I wanted to start with an interesting goal and make sure each step along the way was both educational and fun.

Finally, the laptops at my daughter's school are locked down, so I needed something that required no software not already installed on the machines.

Ultimately, it seemed easier to create my own materials. As a bonus, as mentioned in my posts about writing about code, I'd probably learn a lot in the process. And I did.

RubyStory

The result is a course I wrote called RubyStory and you can grab all of the materials from Github. The details are covered in the readme.

The course materials are intended for teaching to kids. I suppose they could be used for self-instruction, but my assumption is that kids who are ready and motivated to learn programming on their own are probably also ready and motivated enough to learn from a book or a more traditional tutorial.

I recommend Zed Shaw's Learn Python The Hard Way and Rob Sobers' Learn Ruby The Hard Way. Both influenced the storytelling aspect of RubyStory.

The RubyStory materials are intentionally sparse. There's an outline and sample code and handouts. There's a slide deck, but it's mostly just to show the code examples, which students can then type on their own.

The outline provides a concise overview of the topics to teach, but be prepared to fill in details, answer questions and riff a bit as your students require.

I wrote this course with the assumption that the teacher already has some basic programming knowledge. You don't need much:

That's all we use. Even if you know nothing about Ruby, you should be able to pick it up quickly. (I knew almost nothing about Ruby before starting this project.)

Why Ruby?

As you can tell from the minimal set of programming concepts covered by RubyStory, it's hardly language specific nor does it really "teach Ruby." In this case, Ruby is a convenient tool.

First, Ruby is already installed on every recent MacBook. The version installed is not important.

We don't need any special tools to program with Ruby, just Terminal and a text editor. TextEdit isn't the tool I'd prefer — syntax coloring would be a nice feature — but we can live with it for simplicity. (The slides do include syntax highlighting.)

Ruby has very simple syntax and very little necessary punctuation. Whitespace and semicolons aren't that important and there are very few parentheses and brackets to worry about. I've found that kids have enough trouble with accurate typing. Simple syntax makes troubleshooting much easier.

Plus, I wanted to learn some Ruby. And I did.

Next Steps

Please fork the RubyStory repo and give teaching a try. I am continually updating the materials as I teach and learn from the kids — what the enjoy, what they build, what questions they ask, where I can help them go next. Let me know what you learn while teaching with RubyStory.

As written, RubyStory should be easily adapted to Linux systems, but I haven't yet into what additional material would be needed for Chromebooks or Windows. It's on my to do list.

Other than that, I'm now focused on using RubyStory for teaching in my community. I hope you will, too.

#

Rebooting My Toolbox Column - JavaScript

Just a heads up that I'm rebooting ye olde MSDN Magazine Toolbox column over at Visual Studio Magazine.

My January Toolbox picks include 40+ JavaScript Tools and Resources, a look at what's new and useful in JavaScript frameworks and development tools going into 2014. I hope you find it helpful.

#

Beginner iOS Developer Resources

I've been learning the basics of iOS programming for the past few months. The best resources I've found to get started are tutorials — working through the app project and then making my own customizations to further extend my understanding.

Last week I built my first app entirely of my own devising. It's a trivially simple GPS-based app and the details aren't worth sharing (not yet, anyway).

However, there were a number of hurdles along the way. I thought it would be helpful to share some of the useful resources that helped me get over those hurdles.

First, two books that I highly recommend for learning iOS and Xcode are IOS Programming: The Big Nerd Ranch Guide by Joe Conway and Aaron Hillegass (make sure you get the most recent edition) and the Your First iOS 7 App ebook by Ash Furrow. Ash went above and beyond by helping me with a few questions as I worked through his book.

I'm dealing with CLLocationManager, and the locationManager:didUpdateLocations method changed with iOS 6. Matthew at DevFright.com has written some good posts on this including a DidUpdateLocations iOS Example and A Closer Look at the CLLocationManagerDelegate that may help you understand better how to deal with location data.

Daniel Isenhower has a good post explaining Using CoreLocation (GPS) on iOS to track a user's distance and speed. He's really explaining his own PSLocationManager library, but I found getting a grasp on how he built PSLocationManager to be a good tutorial in the underlying CoreLocation framework.

A polished app needs icons and launch images. The details on the sizes you'll need are in Apple's iOS Human Interface Guidelines: Icon and Image Sizes.

Speaking of icons, Mandar Apte created a handy iOS 7 Icon Template for Pixelmator.

Status bar display details changed in iOS 7 and, because my app has a black background and does not employ a UINavigationController, I had a hard time figuring out why the status bar wouldn't appear. (It was there, but it was black. Not helpful.)

Taylor Case wrote an in-depth Developer’s Guide to the iOS 7 Status Bar that explains the status bar changes and what you can do about it. Related reference material: Apple's iOS Information Property List Key Reference.

Something I never did find: a good, current, step-by-step guide for updating developer certificates and provisioning profiles. I muddled through and seem to have pressed all the right buttons in the right order — at least well enough to get the app on my test device — but it was more accident than expertise. Let me know if you come across a useful reference.

#

10 Horror Films

Back in 2011, I pulled together a list of 10 Great Westerns that I'd recommend watching. In honor of Halloween 2013, here's a selection of "horror" films I think stand the test of time.

Special shout out for "Carrie" in recognition of Sissy Spacek's incredible performance, though I don't think the movie stands up all that well as a horror film.

Trivia: During my freshman year at UCLA, some friends and I attended what I believed to be the first public showing of an almost-complete "Evil Dead 2: Dead by Dawn" at the film school. Sam Raimi introduced the film, gave us some background about "The Evil Dead" and his efforts to remake it properly, and then... our minds were blown.

Maybe I'm remembering it wrong. There's nothing I can find on the interwebs referencing this event, so if anyone out there remembers this and can confirm, deny or clarify my memories, please get in touch.

Happy Halloween!

#

These Are My Jams

If you're a music fan who's been looking for a low-key social experience sharing and discovering great music, I recommend checking out This Is My Jam. It takes a while to find and hook up with a circle of followers who share your taste for musical adventure. However, I've found the organic experience of letting the right influences come together quite satisfying.

Here are some of my recent jams. Think of it as a slow-burn playlist. This list is dynamic, so check back in from time to time for new jams... or better yet, just follow me.

Update: Edited the script to show just the last 10 jams.

#

Talking Writing About Code On Technology And Friends

At VT Code Camp 5 in September, I had a chance to sit down with David Giard and talk through some of the issues raised in my Writing About Code session and some general tips for writers.

David posted Episode 287: Terrence Dorsey on Writing About Code today. I hope you find it interesting.

Check out Technology And Friends for more of David's interviews, "talking with smart people about software."

You can also read some of the other posts I've written on Writing About Code:

Writing About Code: Getting Started

Writing About Code: Structure

No excuse not to get writing now!

#

Writing About Code: Structure

In my previous post, I provided some tips about how to get started writing. That's all well and good, but you would probably also appreciate some tips on what to write and how to organize your writing into something coherent and readable. Let's dig into that now.

Many of us were taught a five-paragraph mode of construction: tell us what you're going to tell us, tell us, the tell us what you told us. This is boring, repetitive and evil. Don't do it.

Instead, consider this structure for your writing:

  1. Problem
  2. Solution
  3. Next steps

It's similar to the old five-paragraph model — there's an introduction, a body and a conclusion — but I think this structure better directs the organization of your writing and makes for more interesting reading.

The problem statement

The problem statement is the introduction. It serves two purposes. First, it explains briefly what your article is about. Second, it's your opportunity to grab the reader's attention.

Starting with the second point, many readers think being outrageous or funny makes for a good hook. While that can work, it throws an unnecessary variable into the equation. Are you really funny? Is that enough to hook a reader? Are you sure?

Maybe it's better to just clearly state what you're writing about. Provide some context: what does it relate to (language, platform, type of development...), and why should I care (am I doing it wrong, does this make my code faster, stronger, less buggy...)? This is why I called it a "problem statement."

Readers are often more interested when you clearly define your subject within a the scope of a problem they might encounter and one or more solutions that solve the problem. One approach, of course, is to literally solve a problem, but taking a more abstract view of the problem-solution structure can help guide your writing on other topics as well.

Keep your introduction brief, but it can be several paragraphs if necessary to set up the context in sufficient detail. However, make sure at least one paragraph — preferably the first of last paragraph of your introduction — clearly states what your entire post is about. People who will share your article in social media, aggregators and newsletters will cut and paste. Make it easy for them.

Here's a good example of a brief and to-the-point introduction in an article by Chris Eidhof on Lighter View Controllers.

View controllers are often the biggest files in iOS projects, and they often contain way more code than necessary. Almost always, view controllers are the least reusable part of the code. We will look at techniques to slim down your view controllers, make code reusable, and move code to more appropriate places.

Notice that, in three sentences, Chris explains the context (view controllers in iOS programming), the problem (they're too big and not reusable) and what he's going to explain (a solution for slimmer, more reusable view controllers).

Here's a longer example from Charles Petzold's DirectX Factor column in MSDN Magazine.

High school geometry comes in two distinct flavors: Euclidean geometry is oriented around constructions, theorems and proofs, while analytic geometry describes geometric figures numerically using points on a coordinate system, often called the Cartesian coordinate system in honor of the pioneer of analytic geometry, René Descartes...

In the previous installment of this column... I discussed how to use the ID2D1PathGeometry to render lines in a finger-painting application that runs under Windows 8. Now I’d like to step back and explore geometries in broader detail, and in particular investigate some of the intriguing methods defined by ID2D1Geometry for manipulating geometries to make different geometries.

This is a longer introduction, and I've even left out a paragraph for clarity, but you can see that it includes the same building blocks: a context (geometry in Windows 8 programming, continuing from a previous articles), a problem (geometry is hard, you need to know how it works) and a solution (learn about ID2D1Geometry).

If you can keep your introduction — your problem statement — focused like this, it will help you keep the rest of your article focused as well.

The solution

This is the meat of your article and where you'll spend the most time writing. I won't spend too much time on this as it's really the focus of my first post on getting started writing. You just need to pick a subject and start writing.

The main portion of the article is where you can explain the problem or opportunity in more depth than a concise intro problem statement allows. Stop and provide some more context if necessary, though don't let it distract from getting to the solution. If the problem starts to become the entire article, you might want to rethink what the article is about. Maybe that's another writing project altogether, or maybe you can link to more context elsewhere.

How you write about your "solution" depends on subject and the way you want to organize your ideas. A few common patterns are:

There's not necessarily a right or wrong way to organize the core of your writing. Go with your gut, pick something and run with it. After you complete a draft, if the organizing theme you've selected doesn't seem to be working, don't try to force it. Rather, be open to refactoring and heading in a different direction. Reorganizing takes less effort than re-writing.

Next steps

I'm of the opinion that a blog post or article does not, in fact, require a formal conclusion. If you finish your subject and want to simply stop, that's fine.

This is particularly true of very short blog posts that cover a single, very focused subject. Provide some context and a problem statement, explain yourself through your solution, and done!

If you do want to provide some closure, don't simply restate your original thesis. Instead, you can just sum up quickly: "That's a quick overview of recursive dohickies in action."

Another approach, if there are other considerations, is to qualify your solution. Although I've warned against pedantic, edge-case addicted readers, you don't need to be all-inclusive or all-encompassing in your solution. Just explain that there's more to the subject: "This solution works well for most apps, but edge cases X, Y and Z require additional hemming and hawing." Maybe that's fodder for future writing.

As implied by my heading, it's always helpful to suggest some next steps for the reader: Where to learn more or find additional examples. Other potential solutions or associated technologies. Ideas for further or more sophisticated implementations. You don't need to go on at length. A simple mention and, perhaps, a link, goes a long way.

Use links to your advantage

Links are the lifeblood of the web, and links in your article are good. They let you pull related context and information into your post without having to write it. They also let you recommend quality sources of information and code to your readers, situating your own writing within the larger web of discussion on the subject.

You can (and should) link to your own previous posts. Go back and add links in previous posts if you cover the subject again later. This is particularly important for multi-part series of articles so a reader can find the beginning of the series from any post in the series, then follow through from the end of one post to the beginning of the next. If you make it easy for readers to stay on your site, they will.

Link to other people's posts if they're relevant and helpful. People (readers and writers) appreciate that, and if they've already covered a subject, it saves you from repeating it.

Link to apps, libraries, reference material and anything else that you use or discuss in depth so readers can find and use it too. Make sure you get the name right, though, and it's a nice touch if you check occasionally that links still work.

Comments on the code examples

Code is great. You should definitely include code examples if they're relevant to in your writing. But a code example does not replace an explanation.

If you show code, you should explain the code, even if it seems obvious to you. You wrote it. Of course it's obvious. However, your reader is trying to learn. If it was obvious, they wouldn't be reading... and many of your readers are going to be far less accomplished programmers than you. Help them understand.

In fact, this is where a lot of official documentation falls down. It shows the most basic example, but never take it farther than that. Then it jumps straight to a complete sample app. There's often little explanation of how you get from A to Z.

And as we know, the API is rarely as straightforward to use as the author thinks. There are always inconsistencies and gotchas and misnamed features and things that look the same but do something completely different.

You don't need to show all of your code if it's available somewhere else. Just the important or interesting bits, and a link to peruse the rest.

If there are dependencies, make them clear.

Test your code in a fresh environment (VM maybe) to double-check that there are no unexpected dependencies. "It works on my machine... " is never a good excuse.

The specific coding style choices you make are not as important as consistency and clarity. Pick something and keep with it. It can help to use super-clear naming that you might not use in real code.

More on writing about code

This is part of a series of posts discussing the main points of my "Writing About Code" presentation at Vermont Code Camp 2013. Here are all of the posts in the series:

Writing About Code: Getting Started

Writing About Code: Structure

Now, get writing...

#

More articles...