Avdi Grimm

Along with every other hacker on the planet, I got into programming because I wanted to write games. It wasn’t long at all, though, before I learned that the greatest game of all is teaching the machine to do your will and get things done. I lost interest in game development pretty quickly and moved on to systems and application programming.

My son J. is almost 16, and he wants to write games too. However, in his case I have reason to believe he’s a lot more serious about the “games” aspect than I ever was. So I’m trying to put together a curriculum with an emphasis on game programming. This is a little tricky, since it’s a sub-field I have little connection to.

Here’s what I have so far, with many thanks to the folks on Twitter who helped me narrow down the list: (Book links include my Amazon affiliate code.)

Learn to Program, by Chris Pine. While I already have him working on Hackety Hack, I honestly hesitated to make Ruby his first language. Ruby is a programmer’s language; it has an enormous amount of syntax and many ways to do something. I worry that, as with C++, it will make learning the basics more difficult because it will be hard to separate the fundamentals from the incidentals.

After thinking about it for a while I came around, though. My reasons:

1. Ruby is the language I’m most fluent in at the moment. I’ll have no trouble helping him with any roadblocks he might run into.
2. He’s going to run into OO programming eventually, and I want his first contact to be with a strongly Alan Kay-inspired language. Rather than having to come around to that understanding the long way round, as I did. So no C++, Java, or Python as a first OO language. That pretty much means Smalltalk or Ruby, and of the two Ruby is probably more generally useful these days.
3. Finally, there are some Ruby game development bindings like Gosu that will let him have some fun even before diving into the more hardcore C/C++ stuff.

I suppose Javascript would fit the bill as well, and has the advantage of being ever-so-accessible inside the nearest browser. That said, for all that there is a beautiful language hidden in it, Javscript has more than it’s share of warts. I think in some ways Javascript might have even more of a fundamentals-obscured-by-incidentals problem than Ruby. Tough call though; I could definitely see starting with Javascript, especially if the student were most interested in programming for the web.

Land of Lisp, by Conrad Barsky. A timely book: it’s our next Ruby Rogues book club book. It’s about Lisp, which I want to give J. early exposure to, for ever so many reasons. And it’s about writing games. Win!

C Primer Plus, by Stephen Prata. For someone interested in web applications I might wait C until much later. But if it’s games you want to build, you simply can’t avoid C. Eventually you’re going to find yourself writing OpenGL or DirectX code. Even if you’re writing it in a higher level language, chances are the API documentation will be for the C/C++ API, so a basic understanding of C is essential.

And anyway, a little C goes a long way towards understanding just what the hell the computer is up to.

Blender Foundations, by Roland Hess. J. is particularly interested in modeling. I don’t know jack squat about 3D modeling, but I know Blender is free, Open Source, and widely used. I suspect I won’t need to give him much guidance in this area beyond giving him the tools he needs to get started.

Some C++ book, TBD. I suspect this will be a necessity for understanding later OpenGL texts and working with various game SDKs. If he does well with the earlier languages I’ll probably give him Accelerated C++; or maybe I’ll just go over the basics with him myself without resorting to a text.

OpenGL SuperBible: this one seems to come reasonably well recommended. And honestly I would love to learn some OpenGL along with him.

That’s what I’ve got so far. Any other suggestions?

Let’s say we want a helper method #build_fuzzy everywhere we have a collection of socks.

Sock.build_fuzzy # => #<Sock type: "fuzzy" id: nil drawer_id: nil>
sock_drawer.socks.build_fuzzy # => #<Sock type: "fuzzy" id: nil drawer_id: 123>

At first we might think to put it in an a collection extension module:

class Sock < ActiveRecord::Base
  module SockCollectionHelpers
    def build_fuzzy
      build(type: "fuzzy")
    end
  end
  # ...
end

Now we have to remember to add it to every Sock association:

class Drawer < ActiveRecord::Base
  has_many :socks, extend: Sock::SockCollectionHelpers
  # ...
end

And we also need to include it in Sock:

class Sock < ActiveRecord::Base
  # ...
  extend SockCollectionHelpers
end

…but this doesn’t work:

sock_drawer.socks.build_fuzzy # => #<Sock type: "fuzzy" id: nil drawer_id: 123>
Sock.build_fuzzy # => Raises no method exception for Sock.build()

And anyway, we want this to be available globally without explicitly extending associations.

Next, we try adding a class method to the Sock class. Since ActiveRecord association proxies delegate missing methods to the assoication class, it seems like this should work.

class Sock < ActiveRecord::Base
  def self.build_fuzzy
    build(type: "fuzzy")
  end
  # ...
end

This is a complete failure. While the association does forward the .build_fuzzy call to Sock, once in the call it is operating in the context of the class object, which as we saw before has no #build method.

sock_drawer.socks.build_fuzzy # Raises no method exception for Sock.build()
Sock.build_fuzzy # => Raises no method exception for Sock.build()

However, a slight change makes everything work as hoped:

class Sock < ActiveRecord::Base
  def self.build_fuzzy
    scoped.build(type: "fuzzy")
  end
end

Now when we call #build_fuzzy on the class it builds a fuzzy sock unassociated with any drawer, and when we call it on an association it builds a fuzzy sock with the appropriate drawer ID set:

Sock.build_fuzzy # => #<Sock type: "fuzzy" id: nil drawer_id: nil>
sock_drawer.socks.build_fuzzy # => #<Sock type: "fuzzy" id: nil drawer_id: 123>

All this thanks to the #scoped method, which is aware of the current scope.

Thank you to Dan Kubb for figuring this out for me.

UPDATE: Fixed def build_fuzzy to be def self.build_fuzzy in the last two examples.

Several people have asked about my self-publishing process. I’d really like to write something comprehensive about this, along with code/scripts/config for my whole build stack, but I haven’t had time yet. Until that time, here are some notes on tools I use.

• I do all of my writing in Emacs Org-Mode. (Including this blog post.) Org-Mode has many advantages for technical writing, but chief among them is probably the integration with various Emacs programming language modes. As a result, I am able to execute code samples “live” from within the manuscript and have the output automatically inserted. This saves me from having to maintain separate sample files and manually sync up the manuscript with the examples.
• HTML export is handled directly by Org-Mode.
• For PDF I use Org-Mode’s LaTeX-to-PDF support. I’ve made a number of customizations to the way the LaTeX is generated, something that Org-Mode makes very easy.
• PDF code typesetting is handled by Pygments via the Minted LaTeX package.
• For Mobi and Epub formats I pipe the generated HTML into the Calibre command-line tools.
• I automate the various file conversions and packaging the outputs into a ZIP file with good-ole’ GNU Make.
• I use DPD for digital distribution, payment processing, discount codes, everything having to do with selling the books.
• I use 99Designs for cover designs.

I can recommend all of these tools to anyone looking to self-publish a technical book. I also recommend that anyone thinking of doing this read Jeremy McAnally’s book on the subject; it has a lot of good advice on how to plan, structure, write, and sell an eBook.

The Ruby community has some diversity challenges. I don’t think the Ruby community is any more biased than other tech communities; if anything, I think Rubyists are more apt to make a big deal over offensive content which would be considered business-as-usual in much of the traditionally white-male-dominated tech industry. Which, ironically, may make us seem like a hotbed of scandal.

As a community we also like our colorful gem names. A little while back someone wrote a blog post about some of the more questionable naming choices. Which got me thinking about one of my own gems.

The gem in question is HookR. It’s a library I wrote a few years ago for adding event hooks to arbitrary classes and objects.

The name amused me at the time. Actually, let’s be honest, the name still amuses me. But I’m also concerned it could be offensive. Not in an overt, groping-bottoms-at-a-conference kind of way, but in that insidious way that monocultures tend to be subtly threatening to outsiders without even realizing it.

As I personally read it, it is not gender-offensive since “hooker” is a gender-neutral term. However, it is potentially offensive to sex workers. And anyway, as I’ve noted before, ultimately I’m not the one who gets to decide which of my statements are offensive.

So my question for you: is HookR an offensive name? I realize it’s an unconventional, non-enterprisey name; that much I’m OK with. But is it offensive? Is it amusing, or is it off-putting?

And if you do find it problematic: can you suggest a better name?

Software development is a wonderful field to be a noob in. Perhaps more than any other discipline, there is a wealth of information available for free online–everything from fundamental computer science courses, to the night-by-night learning notes of a master programmer. And, of course, there are millions upon millions of lines of Open Source code free for the reading.

Unfortunately, this embarassment of riches can be as much stumbling block as well as a stepping-stone. You can learn a lot from this information overload, but you can also waste a great deal of time and find yourself with very little to show for it. Personally, I’ve probably wasted thousands of hours in this way over the years. It’s only recently that I’ve come to identify the antipattern behind this waste. I hope that in writing this I can help you to avoid my mistakes.

The pattern usually looks something like this:

Oh man, this web programming stuff is HOT! I need to get in on this!

Let’s see… if I want to program for the web, I’ll need to learn a programming language better suited for the web. And I don’t want to get stuck with on that sucks, so I need to pick the very best one.  Research ALL the languages!

[insert 3 months of reading about Perl, Python, Ruby, and PHP and maybe writing one or two "hello world" examples]

OK, my “hello world” was totally better in Blub than in any of the other languages. But now I need to pick the right web stack for my awesome app ideas. Subscribe to ALL of the blogs!

[Insert three months of voraciously reading web programming blog articles.]

I’ve been reading some of these blogs, and while it seems like everyone is using “Ruts”, it has almost become passé now. Some of the more obscure competitor frameworks look a lot cooler. I’ve read all of their design rationales, and despite the fact that I’ve never written an app in Ruts, I totally agree with their critiques. Yeah, I don’t want to to be stuck in a 6-month- old outmoded framework like Ruts.

Also I need to remember to use the “Box Turtle Pattern” that everyone is talking about.

No wait, now they are realizing Box Turtle doesn’t scale, and the Elephant Plop pattern is the way to go. Man, why did we ever think Box Turtle was a good idea? Whew, glad I hadn’t started my app yet. Dodged a bullet!

Oops, no, looks like Classic Box Turtle coding is making a comeback with a vengeance. Man they are totally right, when you do it correctly it’s way more robust than Elephant Plop.

Gosh, what a vibrant community! These advances are hard to keep up with! When am I ever going to find time to write code?

Oh man, this smartphone programming stuff is really heating up…

Maybe you mastered web programming long ago, but if you’re still learning at all there’s probably some technology that you’re at this point in. Maybe you’re like me and right now it’s client-side JavaScript frameworks. You know it’s there, you know you’re interested, you know where to find out more information about it. And you know that there are a lot of alternatives, and that despite the overwhelming amount of information available it isn’t at all clear where to start.

Without further ado, here is Avdi’s autodidact guide to learning a new programming technology:

1. Do not subscribe to all of the blogs. As yet you have no way of contextualizing the information you will receive from this firehose, and it will just be a paralyzing stream of often-contradictory information.
2. Make a list of the alternative languages/libraries/frameworks/whatever.
3. Pick the most popular one. Here are the criteria for “most popular”:
   • You can easily discover high-traffic fora–mailing lists, IRC rooms, forums–dedicated to it. When you ask newbie questions on these fora, they are quickly answered.
   • There is at least one reputable book about the topic. Books aren’t a perfect indicator of technology viability, but the fact that someone has taken the time to organize knowledge in a systematic fashion is a decent heuristic pointing to a certain level of stability.
   • There is a healthy users group dedicated to the technology, meeting regularly in your nearest big city.
   • At least a few people in the community are too hip for it, and have vocally moved on.
4. Yes, I said the most popular. Not the “best”. You don’t have enough information to figure out the “best” one yet. We’ll get to that. Right now, you need to pick the one where any problem you run into as you learn can be easily googled.
5. Join that local users group. Attend it diligently. You will need those people.
6. Buy, and read, a book about it. Yes, an actual book that you can read on your actual iPad. Or even, (gasp) on paper. Books have some nice properties which most online learning resources lack:
   • They are (relatively) complete. Free online tutorials have a nasty tendency to have gaping “to be written” sections, or to simply stop right in the middle.
   • They usually focus on fundamentals, rather than the latest nifty techniques. Right now you need fundamentals.
   • They have structure. Right now you need structure.
   • Authors of capital-B Books typically spend more time making sure that you’ll be able to reproduce the examples shown in the book using a given version of the tools. Not always (sadly), but usually. For that matter, they usually have fully-worked examples rather than snippets.
   • Fewer hyperlinks, and thus fewer opportunities to be distracted by rabbit holes which lead everywhere except to you writing actual working software.
7. Now use what you’ve learned in a project. For the love of pete do not use it on a project you get paid for, unless you have an explicit understanding with your employer that you are using something you’ve never used before, and will probably get it totally wrong and have to rip it up and start again in six months. Otherwise, use it on a personal project. A small personal project.
8. When you run into trouble, consult the people in the aforementioned fora and local users groups. You are attending those groups regularly, right?
9. Congratulations! You now have the beginnings of context and perspective on this new realm of knowledge. The annoyances which caused those aforementioned hipsters to abandon technology X are no longer academic to you; they are real things which you have also dealt with.
10. With your newfound perspective in hand, review that list you made in step 2. Toss out the projects which have become defunct since you made the list. Pick out one which specifically addresses the problems and irritations you encountered in step 6. Use online tutorials, blogs, whatever; you know the territory now and don’t need to be so pedantic.

This is the framework I’m going to try to stick to, going forward. If you decide to try it, please let me know how it works out for you.

Tim Bray has an article up about static versus dynamic languages, and why he finds the static ones less annoying for Android programming than for web programming. It’s a good article.

Something I’ve noticed over the past few years of web programming is how it’s slowly becoming more like the systems/realtime/embedded programming I once did. Not exactly like it, but similar.

In the early days the difference was stark: as Tim points out, the stereotypical web app is an input/output machine. Requests go in, responses go out. Everything you do in a web app occurs somewhere in between receiving a lump of data and pushing out another lump of data. You don’t have to coordinate multiple threads; the app server does that for you. You don’t have to worry about race conditions; database transactions take care of that for you. It’s a black box: data goes in one end, different data goes out the other.

The big difference Tim sees between web programming and device programming is the number of APIs you typically have to deal with:

4. Touch-screen in­ter­ac­tions.
5. Tele­phony.
6. More radio in­ter­faces, po­ten­tially: WiFi, NFC, and Blue­Tooth.
7. A GPS and com­pass and maybe al­time­ter.
8. Audio gear, in­clud­ing speak­ers and a mi­cro­phone.
9. A cam­era, with a sen­sor and lots of con­trols.
10. An ac­celerom­e­ter.
11. Last but not least, a vi­bra­tor.

The thing is, web programming is starting to look more and more like this, as web programs become nodes in ever more complex constellations of services.

1. Semi-smart clients which are asynchronously pulling data, or expecting you to push data, via Websockets and other technologies.
2. Multiple data stores (e.g. Postgresql and Redis) which may become inconsistent if you’re not careful.
3. A service for sending and receiving email.
4. A service for sending and receiving SMS messages, IMs, or voice calls.
5. Integration with a half-dozen social networks
6. Dedicated work queues for long-running operations

And much like the many data busses embedded programs have to coordinate (RS-232! USB! Ethernet! 1553!), often each of these external  services requires a slightly different kind of impedance-matching code in order to talk to it.

What’s especially reminiscent of  systems programming is that any one of these services can fail. In the primordial web app, a failure of the hardware hosting the app, or the database backing the app, is Not Your Problem. The request either works; or it has a software bug (which is your problem); or the platform fails (which is some poor overworked sysadmin’s problem). But when your app depends on a half a dozen services, any of which could crash, or get really slow, or go just plain wonky at any time, you have to start thinking about failure modes and exception safety and sanity checking and periodic self-tests.

I’m not sure if this new “cloud systems programming” will prompt a resurgence of interests in static languages. But I think it is causing a lot of programmers to rethink how web programs are designed. And a lot of the new thought is eerily familiar. For instance, a lot of web programmers appear to be rediscovering that RPC is a terribly leaky abstraction whether done via UNIX domain sockets or HTTP, and why systems that exchange fire-and-forget messages are almost always preferable.

On the whole, I’m excited about the challenges of heavily interconnected web applications. Yes, it brings with it a lot of the headaches I thought I’d left behind in the systems programming world. But these are interesting problems to solve. And there are few better feelings as a programmer than looking at a system happily humming away, knowing that inside there is an intricate dance going, dozens of inputs being handled and coordinated and dispatched, all according to your careful choreography.

The Ruby community has seen a renaissance of interest in classic Object-Oriented thinking lately. We’re talking about Presenters, and DCI, and Data Objects. But with these new discussions come new problems. Namely: the dreaded pattern terminology debate. He says it’s a Decorator. She says it’s an Adapter. Who is right?

Well fret no more, because I have devoted literally tens of minutes of effort to creating a solution to all of these nagging semantic questions. I give you: the Design Pattern Classifier. Give it a chunk of code, and it will tell you, to within 0.001 of a Dijkstra (the universal measurement unit of software correctness), the name of that pattern!

Enjoy, won’t you?

Configuring Omniauth for GitHub authentication is easy enough. But I needed to optionally add extra permissions to the authentication token. I eventually figured it out, but since I had to piece the steps together from various sources, I thought I’d document what I learned.

A basic Omniauth GitHub setup looks like this:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :github, github_id, github_secret
end

That just gives you a basic read-only authorization, however. If you want to go beyond that, for instance to update user details and manage repositories, you have to pass a “scope” option. The value of the option must be a comma-delimited string of scope names.

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :github, github_id, github_secret, scope: "user,repo"
end

Available scopes include user, public_repo, repo, and gist.

That’s all you need if you always want the same set of priviledges. But what if you want to authenticate some users with more priviledges than others?

The answer lies in the Omniauth “setup phase”. You can pass a :setup option to an Omniauth provider, with a proc which will be executed before the authentication is performed. Inside this proc you can query and alter the request environment. The Omniauth wiki has some basic documentation on how to do this.

I wanted to be able to pass an optional “role” parameter to the /auth/github action, with an app-specific meaning which would be used to determine which scopes to request. In order to encapsulate this logic I specced-out a GithubAuthOptions class:

describe GithubAuthOptions do
  subject { described_class.new(env) }
  context "given no special role" do
    let(:env) { Rack::MockRequest.env_for("/auth/github", params: {}) }

    its(:to_hash) { should be_empty }
    its(:to_hash) { should be_a(Hash) }
  end

  context "given a shopkeeper role" do
    let(:env) {
      Rack::MockRequest.env_for("/auth/github", params: {'role' => 'shopkeeper'})
    }

    its(:to_hash) { should eq(:scope => 'repo') }
  end
end

I wrote the following implementation:

class GithubAuthOptions
  def initialize(env)
    @request = Rack::Request.new(env)
  end

  def to_hash
    if 'shopkeeper' == @request.params['role']
      {scope: 'repo'}
    else
      {}
    end
  end
end

Finally, I added GithubAuthOptions to my Omniauth initializer:

Rails.application.config.middleware.use OmniAuth::Builder do
  # ...

  provider :github, github_id, github_secret, setup: ->(env) {
    options = GithubAuthOptions.new(env)
    env['omniauth.strategy'].options.merge!(options.to_hash)
  }
end

The net result: if I redirect a user to plain /auth/github, they will be authenticated using the standard, read-only scope. But if I redirect them to /auth/github?role=shopkeeper, they will be authenticated with the “repo” scope as well, giving the app the ability to manager their public and private repositories.

The latest Smalltalk-to-Ruby translation in my SBPPRB archive is “Dispatched Interpretation”. It’s one of the bigger ones I’ve tackled so far. I’m not going to go over the whole pattern here; for that you’ll just need to buy a copy of Smalltalk Best Practice Patterns :-)

However, one potentially interesting snippet is this one:

class Object
  def if_false
    self
  end
end

class TrueClass
  def if_true
    yield
  end
end

class FalseClass
  def if_false
    yield
  end

  def if_true
    self
  end
end

This is another take on Smalltalk-style method-based control flow. Specifically, the following Smalltalk idiom:

aPredicate ifTrue: [ ... ] ifFalse: [ ... ]

The key difference here from our last foray into Smalltalk-style flow control is a special implementation of #if_true on FalseClass, which ignores the given block and instead returns itself. This enables a call to #if_false to be chained onto the #if_true call, and the #if_false defined on FalseClass then yields to its block in order to execute the negative case.

On the flip side, if the initial object is true, then TrueClass‘ #if_true method is hit, which yields to the given block. It returns the result value of the block, which, assuming it is not false, will respond to #if_false with the do-nothing method we defined on Object. There is an obvious bug in the case where the block given to if_true does, in fact, return the false constant. I’ll leave fixing that bug as an exercise to the reader.

Bugs aside, the upshot is a chained call idiom which looks not unlike the Smalltalk keyword argument version:

object.if_true{ puts "true!"}.if_false{ puts "false!"}

As with some of the other Smalltalk-in-Ruby articles, I put this forward as a curiosity. If you really want to use method-based flow control pervasively, Ruby might not be the best language for it.

A few people have asked for recommendations of good foundational Object Oriented Programming texts. The truth is I’m kind of behind on my formal OOP reading, and some of the early texts I read I wouldn’t recommend. My first proper OOP book was Object-Oriented Analysis and Design with Applications by Booch, and while it’s not a bad book, I remember it being awfully dry.

Honestly, most of what I know I learned from surfing WikiWiki. It’s still the best source of collected software development thought on the planet, albeit not the most organized. I highly recommend killing an hour or hundred link-surfing WikiWiki.

I haven’t read all of it yet, but Object-Oriented Software Construction, by Bertrand Meyer, is probably one of the better guides out there about how to think of the world in terms of objects with well-defined responsibilities.

I can wholeheartedly recommend Kent Beck’s Smalltalk Best Practice Patterns. It masquerades as a book about Smalltalk, but it’s really a book about how to write clean OO code all the way down at the method level.

I have a long list of OO books I’ve been meaning to get to. I hear good things about both Domain-Driven Design and Growing Object-Oriented Software, Guided by Tests. I’ve always wanted to read some of Rebecca Wirfs-Brock’s work, such as Object Design: Roles, Responsibilities, and Collaborations, as well as Uncle Bob’s take on the subject. Speaking of Uncle Bob, his Ruby Midwest keynote piqued my interest in Ivar Jacobson’s book on use-case driven OOP.

Obviously, this list is far from comprehensive. So I’d like to open the floor: what books do you consider essential first-level Object Oriented reading material?

A few months back I posted a design for an experiment on my blog. The goal of the experiment was to find out whether it would be possible to use a microblogging tool to narrate our work with the intention of making better performing virtual teams.

Over the last two months, the direct team that I work in (consisting of 18 people) basically participated in the experiment in the way that it was designed: They posted constant, daily or weekly updates on our Yammer network. Each update would describe things like what they had done, who they had spoken to or what issues they had encountered. Occasionally the updates were peppered with personal notes about things had happened or were going to happen after work.

Methodology of the experiment

There was no formal (or academic) research methodology for this working experiment. I decided to use a well-considered survey to get people’s thoughts at the end of it. Out of the 18 team members 17 decided to fill it in (in the rest of the post you can assume that n=17). The one person that didn’t, has taken up another role. This means there is zero bias in who answered and didn’t answer the survey.

I find it more interesting to zoom out and look at the methodology of this experiment as a whole. To me doing things like this is a very good approach to change in the workplace: a grassroots shared experiment with commitment from everybody working towards solutions for complex situations. This is something that I will definitely replicate in the future.

Didn’t this take a lot of time?

One concern that people had about the experiment was whether it would take a lot of time to write these updates and read what others have written. I’ve asked everybody how much time on average they spent writing status updates and reading the updates of others. This turned out to be a little bit less than 5 minutes a day for writing the posts and slightly over 5 minutes a day for reading them. The standard deviations where around 4.5 for both of these things, so there was quite a big spread. All in all it seems that narrating their work is something that most people can comfortably do in the margins of their day.

Barriers to narrating your work

Designing the experiment I imagined three barriers to narrating your work that people might stumble over and I tried to mitigate these barriers:

• Lack of time and/or priority. I made sure people could choose their own frequency of updates. Even though it didn’t take people long to write the updates, just over 50% of the participants said that lack of time/priority was a limiting factor for how often they posted.
• Not feeling comfortable about sharing in a (semi-)public space. I made sure that people could either post to the whole company, or just to a private group which only included the 18 participants. Out of the 18, there were two people who said that this was a limiting factor in narrating your work (and three people were neutral). This is less than I had expected, but it is still something to take into account going forward as 12 of the participants decided to mostly post in the private group.
• Lack of understanding of the tool (in this case Yammer). I made sure to have an open session with the team in which they could ask any question they had about how to use the tool. In the end only three people said that this was a limiting factor for how often they posted.

The qualitative answers did not identify any other limiting factors.

Connectedness and ambient team awareness as the key values

Looking at all the answers in the questionnaire you can clearly see that the experiment has helped in giving people an understanding of what other people in their team are doing and has widened people’s perspectives:

A quote:

I enjoyed it! I learned so much more about what my colleagues are doing than I would have during a webcast or team meeting. It helped me understand the day-to-day challenges and accomplishments within our team.

and:

The experiment was very valuable as it has proven that [narrating your work] contributes to a better understanding of how we work and what we are doing as a team.

People definitely feel more connected to the rest of their team:

There was practical and social value in the posts:

A lot of people would recommend “Narrating your work” as a methodology to other virtual teams:

What kind of status updates work best?

I asked what “Narrating your work” type of update was their favourite to read (thinking about content, length and timeliness). There was a clear preference for short messages (i.e. one paragraph). People also prefered messages to be as close as possible to when it happened (i.e. no message on Friday afternoon about what you did on the Monday). One final thing that was much appreciated was wittiness and a bit fun. We shouldn’t be afraid to put things in our messages that reveal a bit of our personality. Sharing excitement or disappointment humanizes us and that can be important in virtual teams (especially in large corporations).

Personally I liked this well-thought out response to the question:

The best posts were more than simply summing up what one did or accomplished; good narrations also showed some of the lines of thinking of the narrator, or issues that he/she encountered. This often drew helpful responses from others on Yammer, and this is where some some additional value (besides connectedness) lies.

It made me realize that another value of the narrations is that they can lead to good discussions or to unexpected connections to other people in the company. This brings us to the next question:

Public or private posts?

The posts in the private group were only visible to the 18 participants in the experiment. Sometimes these posts could be very valuable to people outside of the team. One of the key things that makes microblogging interesting is the asymmetry (I can follow you, but you don’t have to follow me). This means that posts can be read by people you don’t know, who get value out of it beyond what you could have imagined when posting. What to you might sound like a boring depiction of your morning, might give some stakeholders good insight in what you are doing.

So on the one hand it would be very beneficial to widen the audience of the posts, however it might inhibit people from writing slightly more sociable posts. We need to find a way to resolve this seeming paradox.

A way forward

Based on the experiments results I would like to recommend the following way forward (for my team, but likely for any team):

• Don’t formalize narrating your work and don’t make it mandatory. Many people commented that this is one aspect that they didn’t like about the experiment.
• Focus on helping each other to turn narrating your work into a habit. I think it is important to set behavioural expectations about the amount of narrating that somebody does. I imagine a future in which it is considered out of the norm if you don’t share what you are up to. The formal documentation and stream of private emails that is the current output of most knowledge workers in virtual teams is not going to cut it going forward. We need to think about how we can move towards that culture.
• We should have both a private group for the intimate team (in which we can be ourselves as much as possible) as well as have a set of open topic based groups that we can share our work in. So if I want to post about an interesting meeting I had with some learning technology provider with a new product I should post that in a group about “Learning Innovation”. If have worked on a further rationalization of our learning portfolio I should post this in a group about the “Learning Application Portfolio” and so on.

I liked what one of the participants wrote:

I would like our team to continue as we have, but the important steps to take now are 1) ensuring that we stay in the habit of narrating regularly, 2) showing the value of what we achieved to other teams and team leads, and 3) ensure that there is enough support (best practises etc) for teams that decide to implement [narrating your work].

I have now taken this as far as I have the energy and the interest to take it to. I would really love for somebody to come along and make this into a replicable method for improving virtual teams. Any interns or students interested?

(This article is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Netherlands License. It originally appeared here: http://blog.hansdezwart.info/2011/07/19/reflecting-on-the-narrating-your-work-experiment/)

Announcements:

• I’m looking for a sponsor so I can do the podcast on a more regular schedule! Contact me if you’re interested.
• Get your free copy of the Dispersed Team Kick-Start Guide by signing up to the Wide Teams mailing list.

Show notes:

• Dan blogs at dan-menard.com and is @dan_menard on Twitter.
• Macadamian
• How to work with someone 12 hours away
• Yammer
• Smartboard
• The Wine project

Show notes:

• John Hawkins is @vegasgeek on Twitter
• 9Seeds LLC
• The Event Ticketing and Affiliate Manager WordPress plugins
• 9Seeds sponsors WordCamp conferences

I really hit my work zen at home, in my office, and mainly for two reasons.  The first is the ability to control distractions at home, and the second is surrounding myself with what I love.  Aside from my music it’s quiet.  It’s decorated with all sorts of colorful and fun things that help give me inspiration when I need it. I know where to find anything I need.  I find that being able to influence your own environment is very important.

–David Browning, co-founder of Two Guys

–Sahil Parikh, Founder of DeskAway

Being able to watch my daughter’s class assembly because I can catch up the time later in the evening when she is tucked up in bed.

–Marieke Guy, blogger at Ramblings of a Remote Worker

Sitting somewhere around the house (porch/office/living room), only to have the husband/kid come up and mention that is too beautiful a day to be working and suggest we go out and do X (ride the motorcycles/ go to the beach/ swim in the pool).

Since I telecommute (and assuming that is not during a required work period), I can agree and go enjoy the beauty day with them. Work can be made up later that night.

–Ligaya Turmelle

For me the best part of working remotely is that it allows me to change my environment.  There are times when I need to be heads down in a task that is monotonous and dull and there are environments that are more conducive to that.  Other tasks require creativity, which is something I don’t find easy in a cube.  By working remotely I can go to that coffee shop that helps me find my writing muse or one that is great for heads down productivity.

Environment can definitely change our moods and in doing so it can also change our ability to perform well.  By working remotely I’m allowed to change my environment as needed to insure that I’m able to complete work in a way that is most effective for me.

–Jessica Dally, Project Manager at TechSoup

My moment(s) of remote work zen are often first thing in the morning. I have a big picture window in front of me and the sun hits the floor next to my desk. My tuxedo pseudo-kitten (8 months old) lays in it seemingly sound asleep. As the minutes pass and the sunbeam move, he slowly rolls over and over steadily following it across the room.

He never opens his eyes, but he looks comfy.

–D. Keith Casey, Jr., Chief Stuff Breaker at Blue Parabola

I love our morning skype video scrums. Often Brad and I have our daughters on our laps and Reid will bring his dog up so he doesn’t feel left out.

–Shane Pearlman, CEO of Shane & Peter, Inc.

1. In the car, tethering my phone to my laptop, while also talking to a customer about an urgent issue, run through the fix/test/check-in/deploy process, while my wife drove me and the kids to Grandma’s house.
2. After picking up a sick child from daycare and comforting/medicating them, knowing that I can get back to work later, and be able to take care of my family, and meet client deadlines at the same time.

–John McCaffrey, Rails Developer, blogger at Ruby on Rails Performance Tuning

What about you? What’s your moment of remote work zen?

Show notes:

• Shane Pearlman is @justlikeair on Twitter
• Shane & Peter
• Check out the Shane & Peter Lifeblog
• Redmine
• Adium
• Coworking
• Freelance Camp

There are ways remote workers can overcome these challenges with different communication techniques.  Knowing when to use e-mail, the phone, and instant messaging can also help everyone communicate more effectively.

1. Use the phone for urgent matters. If you have a question or a matter to discuss of urgent nature, you want to reach your team member over the phone so that you may receive an immediate response.  The telephone also allows you to obtain clarity on a response immediately if you have further questions.  Of course, there are times when you reach voicemail instead.  In that case, you want to leave a message that clearly indicates you have an urgent matter that needs to be discussed (if you have a specific deadline, indicate what it is), when you called, and request an immediate call back.
2. Gather your thoughts before communicating. Compile your thoughts, points and questions in one e-mail or on a piece of paper before going on a call.  If you are using e-mail and have two or more points or questions, use bullet points.  This makes it easier for you to receive responses to all items and for the team member to review and respond to you.
3. Respond promptly. It is important to respond promptly to all communications.  It’s already a challenge for team members to not be able to walk over to you with a quick question.  You want to make communication easy for everyone.  Your team members will appreciate your prompt responses and will catch on to this protocol.  In return, you should also receive prompt responses for any questions you have from team members.
4. Get to know your team members and let them get to know you. Face time helps a great deal when getting to know one another.  For remote workers, utilizing video conferencing such as Skype when appropriate helps with interpersonal communications.  Also in any day-to-day communication, whether via the phone or e-mail, make a point to be more personable by asking how your team member’s day is going, how their weekend was spent, and share with them what’s going on at your end.
5. Use “please” and “thank you.” E-mail and texting can leave a cold message.  There are times when the tone of a message can be misinterpreted.  By utilizing words such as “please” and “thank you,” it ensures your message’s tone remains positive and it also doesn’t sound demanding.
6. Provide and/or ask for confirmation. Before ending calls where direction is provided, always summarize what you understand to be the next steps and include deadlines.  This ensures both of you are on the same page.  A brief e-mail summary on to-dos is also helpful in keeping everyone on the same page.

Title photo “Hotline” by Grant Hutchinson

• Set Up Remote Colleagues With the Apps They Need Using Ninite: Online Collaboration «

  • Ninite has a selection of many of the most commonly used apps, including browsers, IM clients, media players, office apps, Flash, PDF readers, security tools, utilities and even some of WWD’s favorite tools, like Dropbox, Evernote and KeePass. The installer installs the most up-to-date version of the apps; running the installer again will update the apps to the latest version.

     

• iPad 2: The Best Tablet for Distributed Teams Just Got Better: Online Collaboration «

  I’ve talked about the importance of  a “comms appliance” for remote workers; the iPad 2may just be the best device yet for that role.

  tags: communication videoconferencing ipad

  • People who think that adding a camera to the iPad 2 is just a minor improvement aren’t people who work with remote team members and clients. Videoconferencing is increasingly popular; you need only look as far as the success of Skype and the rise of competitors to that service to find proof of that. The value of face-to-face communication actually increases as in-person dealings become more of a rarity, and it won’t be long before third parties join Apple’s FaceTime in the video chat game, and multi-person group video chat is right around the corner

     

• Teleworkers on the rise

  Great article about some of the advantages of working remotely.

  tags: telework

  • Carr said the benefits of teleworking greatly outweigh the stress of sitting in traffic and being distracted by the office atmosphere. 

    “It becomes clear that the best employees are the ones not stuck in traffic,” he said.

     

• How to Work with Someone 12 Hours Away | Macadamian Blog

  Terrific article about one team’s experience with a very widely dispersed organization.

  tags: wideteams telework

  • It’s awesome when the critical path moves seamlessly from North America to Western Europe/Asia. For example, say you have 80 hours of tasks that can’t be done in parallel. A local team will need two weeks to do these tasks. A global team, on the other hand, can work separate 8-hour shifts and get them done in one week. That’s twice as fast!

    It’s awesome when my code is tested while I sleep. A small team of local developers can be extremely efficient when paired with a remote QA. I spend my day fixing bugs and adding features, and by the time I come in the next morning, these issues have been tested and either re-opened or closed. Prioritizing tasks is a breeze, and we don’t lose as much time on code freezes leading up to a release.

     

     

• Google Docs Turns Its Comments System Into a Conversation System – ReadWriteCloud

  tags: collaboration wideteams documents office remote communication

  • The new comments system works like a conversation thread on a Facebook, complete with @replies. When someone is tagged in a conversation, they will receive an e-mail notification. The user can then either click-through to the document, or simply respond to the e-mail. All the conversation is captured and stored in Google Docs with the document. If the notifications become too much, users can mute notifications.

     

• Implicit Communication and Virtual Teams | Leading Virtually

  Really insightful article about high-context and low-context cultures, and the different ways they can react to the challenges of remote work.

  tags: communication

  • Indicate to your team that research for virtual teams shows that, because of the challenges inherent in virtual work, being a little more explicit in communication is probably necessary. This may mean more of a challenge to high-context team members who are used to implicit communication. To help them feel more comfortable with being explicit, frame virtual work as a totally new way of doing things with a lot of learning to be done along the way.

     

  • team members will create rules of engagement which make explicit the what, when, who, and how of decision-making and communication within the team. Among the things covered by the rules of engagement are the nature and frequency of communication, communication media to be used, the values that the team will live by, the response times for messages, how conflict will be resolved, and how the decisions will be made, including who makes what decisions.

     

Show Notes:

• Susan Tenby is @suzboop on Twitter
• Jessica Dally is @jessicadally
• TechSoup is @techsoup on Twitter
• Nonprofit Commons is @npsl on Twitter.
• A video about NPSL’s work in Second Life
• Second Life
• Hypergrid Business, a blog devoted to “enterprise users of virtual worlds”
• Community Voice Mail
• 5PM project management tool
• Evernote
• HootSuite
• BaseCamp

When you don’t occupy the same office for the same period of time every day with your co-workers, you can’t walk to your co-worker’s desk, or turn around in your chair to have a chat about what you’re working on. There is no water cooler to mill around get in the loop on what’s happening, and having lunch together is difficult. Differences in location, timezone, and working hours, can all combine to make you and the members of your team disconnected from each other.

This disconnect is difficult for both sides: it’s easy for work to be duplicated, or misunderstood. It’s also easy to get lost in details and disappear when your teammates might have helped you with some of the problems you were having trouble with. None of these problems are insurmountable: they are all easily solvable with a few tools and practices that are easy to adopt. The practices outlines in this article will help your team communicate more effectively, and help everyone feel better connected to their co-workers.

Daily Stand Up

When working on-site, you have a very well defined start to your day: arriving at the office. When working remotely, it’s possible to find it difficult to get started, or find that you don’t really know where to start, or not know what related tasks others may be working on. One way to encourage everyone to have a clear idea of what’s going on around them is to have a quick daily team meeting. This will allow everyone to catch up with their teammates, and is a great first step to encouraging active involvement in the project.

For a co-located XP team, we would have a Stand Up, and there’s no reason a remote team can’t do the same. Of course, the details are slightly different. Some enjoy starting their day with the daily meeting, because it gives them a clear idea about what they should be working on, and how it fits with what their co-workers are working on. A remote team with members in many timezones will probably have to pick a time for a daily meeting that is not first thing in the morning for everyone, but that overlaps the working day for as many people on the team as possible. In XP, we call the meeting a “Stand Up” because we have the meeting standing up to remind everyone that it should be kept short. With remote work, few people are standing up, so extra care and attention may have to be paid to keeping the meeting a reasonable length.

There are many tools that can facilitate this, and unfortunately none of them are great. Skype, or a conference call line, is a good way to have a voice call. If you want to spend some money in order to see your teammates’ faces, you can purchase a product like Adobe Connect which allows many people to video conference in a window that looks like the opening of the Brady Bunch. Regardless of which time or tool you use for your meetings, the act of having the daily meeting is a huge benefit to all members of the team.

Group Chat

One of the things that I advocate for all distributed teams is to have a group chat forum. An IRC room may work just fine for you, but requires additional tooling to allow team members to see discussions that took place while they were offline. Web based tools like 37signals’ Campfire provide private chat rooms, at a relatively small cost. There are also Campfire applications for desktops and mobile phones that allow you to improve on the user experience of the web site, or take your team on the road with you.

Once you have a group chat, it’s important to use it. While I’m not a fan of hard “rules” and strict “process”, your group chat should be made a part of the culture. To encourage participation, make it fun and light. It doesn’t always have to be about work. It’s much easier to feel connected to the rest of your team when you get to know them on a personal level. Talk about the weather where you are, what you’re doing after work, and link to the great articles you’ve read that help you improve your skills at your job.

Perhaps you have an office with only a few remote people, or half of your team is in a single office, it’s still important that the group chat become part of the team’s culture for everyone. This will allow some of the “in office” staff to enjoy some of the same freedoms that the remote workers enjoy, by enabling them the communication tools to work from home from time to time without missing any of the discussions. It will also ensure that the remote workers don’t feel left out, or less important than those who are in the office.

Mailing Lists

Mailing lists are another great tool for communicating. Open Source projects, which are some of the best examples of successful distributed teams, have been using them for decades to communicate. Mailing Lists aren’t as immediate as group chat, but they give you a way to contact all members of your team in a way that you know will be read and internalized.

Mailing lists are great for things that are important for everyone to see, not just the people who are at their desk right this second. For instance, you might write about an appointment that you have to go to and will be away from your desk: “I have a colonoscopy tomorrow, so I will miss the morning meeting and be unable to sit for the rest of the day.” Another great use of a mailing list is to describe a new idea, or something you’ve found in the code, in a way that everyone gets to see at a time that is convenient for them. Such an email might start out like “I just looked at our five slowest tests, and they all use the FooBaz class, so I profiled it and here’s what I’ve found.”

A team mailing list may not be for everyone. For especially small teams, or for teams who all work on a fixed schedule in the same time zone, they may be a bit heavy. Mailing lists are just one of a number of tools that can be utilized to make remote working easier and more enjoyable for everyone involved.

Status Updates

In a traditional office, you can generally find out what your co-workers are up to, what kinds of problems they’re solving, and how you might help them through passive interactions. The water cooler, walking down the hall, or sharing a table at lunch all provide additional interactions with your co-workers that remote members don’t get. Non-verbal cues are also easier to pick up on when you’re in the same physical location, but are completely lost in remote working situations. You may notice that your co-worker is puzzled by a problem, or frustrated by something, simply by observing their body language, hearing their cursing, or dodging the thrown chairs.

Yammer is a tool for providing Twitter- or Facebook-style status updates. Yammer is closed to groups, so only the people you allow in your group can see your status updates. This allows nice bite-sized communication that is less invasive than group chat or instant messaging. Yammer is great for  simple “heading out for lunch”, which will let your co-workers know you’re away from your work without being invasive. When working through a problem you might write “wishing I had a widget that could frobnicate this foobar”, and a co-worker who knows of such a widget might see this and help you out.

One of the benefits of status updates over group chat, is that it’s non-intrusive. It’s meant for broadcast communication, that won’t make your co-workers feel like they need to be present for the conversation before it goes away. It has some benefits over email in that the statuses are smaller bite sized thoughts, which can be ignored if needed, but contain valuable information if you want it.

Conclusion

Team members feeling left out is one of the biggest costs of a remote working team. In order to get the most out of our remote working environment, we have to encourage interaction. The resulting team will be stronger, and more effective as a result. There are many other tools and practices that teams can adopt to help them be more effective, this article just touches on the basics.

Show notes:

• Sahil Parikh is @sahilparikh on Twitter.
• Check out DeskAway at DeskAway.com / @deskaway