Elf Sternberg

I love being able to combine one of my favorite design techniques with my latest infatuation.  It makes my hair tingle.

“Gamification,” as any buzzword-compliant high-priced consultant will tell you, is the process of adding game mechanics to a website in the desperate hope that trivial reward mechanisms– badges, stickers, and made-up titles straight out of your D&D years– will encourage your customers to come back and visit your website again.  At least, that’s what gamification appears to be on the surface.  That is a shallow and useless description.  Badges, “experience points” and useless labels will not encourage anyone to use your website.

“Story cards” are a specification tool used in Agile and eXtreme Programming development.  A story card (usually a hand-written 3×5 card) describes the “happy path” of a user doing something useful with your software: “The user logs in,” “the user searches for a movie,” “the user watches a movie,” “the user likes a movie,” (here, “likes” is emphasized to record that “liking” is an application-specific verb).  (I use the example of a movie-selling website because I work for a movie-selling company.)  Before a development sprint, the team sorts the cards by priority, makes estimates as to how long it would take to write code that would fulfill each story, and then begins bargaining to establish who has responsibilities for each story, along with the usual ensuring that one developer’s track will not confound another’s.   A sprint is made, and then the developers assess.  A “story” is a small, atomic action a user can take with your software.

Deep, rich websites typically have dozens, if not hundreds, of stories.   Often, many of those stories will go completely ignored by your users.   They may be obscure or difficult to find in your navigation.; alternatively, their value to your users may not be obvious.  As a website owner, you want users to try out every story you have; you never know which constellation of the many stories your website supports will be the one that hooks any individual user to engagement.   If you don’t encourage your user to try out everything, you’re wasting your website.

Gamification helps prevent this waste.  It’s is an incredibly easy concept to grasp; you could write a Django app or Rails plug-in to support it in a single afternoon.   The gamify application looks like this:  For any given story (usually, “gamification experts” will call this a “user action”), the customer accrues a certain amount of currency. (Do not be confused by this word.  It does not imply money, or “virtual currency”; it’s merely a tally of whatever it is your tracking the accrual of: experience points, votes, the number of times a user has reviewed a movie, the consistency with which a user has visited your website.)  At some point (maybe even immediately), your software awards something to the user.

This is where the whole “badges, levels, titles” thing gets confusing– and annoying.  Because rarely does the user want a badge, a level, or a title.  What the customer wants is enlightenment. What you want is engagement. What your software awards to the customer should not merely be a badge, a level, or a title– your software should award the customer the information and tools needed to engage more.

Gamification is not turning your website “into a game.”  That’s stupid.  If I want a game, I’ll fire up the Playstation.  Better yet, I’ll go find my kids and a deck of Uno cards.  Gamification is the mechanism by which your website’s user manual is turned into easily digestable and entertaining awards, leading users by the hand from one capability to the next.

So get out your story cards and arrange them, not in the order in which they could be accomplished by the developer, but an order in which you want a customer to encounter them.   Sometimes, this order will be linear, but more often not.  Lay the cards on the table, with “sign up” at the top, and then the “natural” things the user would do as a second line of cards underneath, then more complicated things.  Maybe down at the bottom you could put the “epic win” cards of your website: the most popular filmmaker, or most respected reviewer, or whatever.   Now, for each card, you have to come up with a parallel game card: write down what currency we track in this story, and when the user has completed the story, what award will lead the user to other cards.  The award is a fragment of your user manual: “Now that you’ve done X, you can also do Y!”  Now, as an added layer, write a tracker for each event, tally the user’s currency, and design the award.

Gamification is the process of enlightening your users about how they can grow as users of your website.  If you have mild engagement (that is, the customer didn’t flee at the first sight of your home page), you have an opportunity to educate the user about what to do next.  You can do that with a Big Page Of Instructions, or you can do it incrementally, gradually, and with a sense of achievement.   The mechanics are easy.  So damn trivially easy I don’t see why VCs are giving third-party “gamification tracking” companies like Big Door and Bunch Ball millions of dollars.  The real trick to gamification is at the other end, at your website: your active customers know what’s epic and important about your website.  Do some analytics, figure out what your active customers already know, and then figure out how to lead new users down those same pathways in a gentle and entertaining way.

This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com

Inspired by Five Web Files That Will Improve Your Website, I decided this morning to implement OpenSearch on the Indieflix Website. (It’s not up yet, we’re still beta’ing it, and it’s along with a massive list of changes that still need testing, so don’t go looking for it.) OpenSearch is a way to turn your site’s search feature into an RSS feed: you define for (other) search engines how and what you search on your site, and it automagically creates relationships so that your site’s search can be included in remote results. Normally, the results would be returned in an XML container for RSS or Atom, but HTML’s fine for some applications.

As a trivial example, I’m going to add your website’s search engine to Firefox’s drop-down of search engines. I’m going to assume that you already have a search engine enabled on Django. Haystack, or Djapian, or Merquery, or something along those lines.

First, you need a file called opensearch.xml. I put this into my template base directory:

( Code behind cuts )

Obviously, there are things to modify here: your real short name, description, image and search paths.   You know where those go.

This goes into your base urls.py (if you haven’t imported direct_to_template, now is the right time):

( More code behind the cut )

Again, if you changed the names or locations of the template, you have no one but yourself to blame if stuff blows up.   The name opensearch.xml is not particularly important or required, in either the template (obviously) or in the deployed URL.   To make external spiders and browsers know about your website, this goes into your base.html or site_base.html, somewhere in the headers with your metainformation and style sheets and so forth.

( Final cut )

And that’s it.

To test this, load up your home page in Firefox, then click on the search bar’s drop-down. You should see your “short name” offered as a search plug-in. Select it and type some search terms, and Firefox will know to use your search engine, and the results will be from your site.

Pretty cool.

This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com

I recently implemented a new subsite for IndieFlix using LessCss, the Leaner CSS metaframework. LessCss is a programming language that abstracts CSS out into a hierarchal language, where instead of writing:

#header { ... }
#header img { ... }

You write:

#header {
    ...
    img { ... }
}

Which, believe me, makes a whole lot more sense. Even better, if you’re fond of the clearfix technique, then you’ll see why I fell in love with LessCSS. I had a long sidebar object, and I realized that I needed to make it clearfix to deal with some float issues. I had .clearfix { ... } defined already in my CSS, and I had my “.social-networks” class that I wanted clearfixed. LessCSS let me write:

.social-networks {
    .clearfix;
    ...
}

And it all worked the way I expected it to, without my having to clutter up the HTML with layout hacks.

Yes, this means that there are duplicates in the CSS LessCSS actually spits out, but that shouldn’t matter, any more than you care about bitsequence duplication in a large C++ program’s object code. I tend to look down on metaframeworks; my experience with using Ruby to write Scriptaculous code, or GWT, is that unless I want to jump through strange hoops I’m limited to expressing in Javascript only what can be expressed by the writers of the Ruby or Java-based framework.  This problem is made worse by the promise of not having to learn Javascript to be expressive in it.  I call shenanigans.   The win for using any framework has to seriously overwhelm the loss of expressiveness. I don’t bemoan losing the expressiveness of assembly language when I write in Python (although if I did have a problem that needed assembly language, I’d write in ASM, build a C wrapper, and compile the thing into a Python module… because I know all three of those languages^*), and the only thing I lose using LessCSS is browser hackery, which I shouldn’t be doing anyway.

The containerization of cascades is such a clear win for me that I can’t imagine going back to doing CSS by hand. Well, I can, I just wouldn’t want to.

LessCSS does not carry your CSS comments from its source file to the CSS output, so it’s inappropriate if you need browser hacks that rely on poor comment parsers (I’m looking at you, Opera) or have alternative uses for comments in CSS (such as Wordpress’s style.css file does).

---

[*] Okay, I studied Motorola 68K assembly, which is a far cry from x86 assembly. Back in the 80’s, everyone “knew” the x86 chipset was junk and Motorola’s native multitasking cores were the future. Then Apple had to screw up using the multitasking features, Amiga and Atari blew it, Microsoft, IMB and Intel continued to chug along, and we’re left with the x86 series. This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com

A friend of mine pointed me to the website of CB Richard Ellis, a real-estate investment and management house with a big footprint here in the Pacific Northwest.

Their hiring website is a horror. No, really, go look, unless you’re an epileptic. (Sadly, the effect only seems to be present for Firefox users. Opera, Chrome, and IE6 didn’t show the evil.) Then go read The Federal Electronic and Information Technology Accessibility Standards, better known as “Section 508″, and document how they’re out of compliance. (Hint: Section 1194.21k).

I fully believe it’s possible to design very attractive websites that don’t violate Sec508. CBRE has failed on a galactic scale with this abomination.

If you’re not a Firefox user, here’s the horror: Every input button has this added to its CSS: text-decoration:blink;.

Yes, that’s right. Every input button is set to “blink.” I don’t know what’s worse: that the people who wrote their site thought that was cute, or that Firefox honors it.

This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com

While visiting with friends and family this weekend, I ran into a long-missed flame who said she was frustrated because she’d gone back to school to renew her web design business, last heard from about a decade ago, but the school seemed insistent about teaching her programming instead. Her head was full of PHP and Javascript, when what she really wanted to do was “draw pretty pictures” and hand them off to the developers.

Curious, and because I’m always looking out for good designers, I asked her what her design aesthestic was.  Did she like grunge or clean?  Organic textures or vectors?  Dark or light?  What did she think of grids?  How about Minimalism? Typography?

I’m afraid in my high-speed way I hit her with all of those questions in one long stream and she stared back at me like a deer in the headlights.  She’d never heard of any of these terms being used in conjunction with her current studies or practices.  Now, admittedly, these were terms from poster and illustration work back in 1999 that had only just begun the leap into web design practices.  When she jumped out I was working with flat, vector advertisement people who thought the height of design sensibility was the Taco Salad typeface (Ugh, totally hate that one now, even though it’s immortalized in a design I did in 1997 that will live forever and that I can’t take back).

I’m still much more of a developer than a designer, but I keep a daily zeitgeist feed of what’s hot in the design world, and I collect and keep tickler files, so when I’m in need of a new design, I can collect a few and when I hire a designer I can say, “I want a feminine design, slightly three-d (drop shadows are adequate, some pseudo-perspective boxes would rock), with a wine-purple background to suggest sensuality and mystery.  The objective has some infographic weight, so a stable grid would be a good idea.  Let’s talk information architecture and session flow.  I want something that’s a mash-up, not a compromise, between a website that sells porn and one that sells high-end cosmetics.  The background has to be IUI compatible.” Or, “I need an info-rich magazine layout for the adult story set, something way sexier than what’s currently out there, but with enough whitespace that each article can successfully compete with its neighbors for eyeballs based on content about the length of a double-tweet. I need a bumper-sticker-sized banner, with a solid typographic cascade, for the story of the hour. And I need some Section-508 compliance in the site, so high contrast is a must.” Or, “I need a web 2.0 throwback site for a low-end web app. A simple thing. Let’s do green and white, subtle gradients and high-contrast borders, unless you’ve got something burning that I can buy into.”

Being able to talk this way with designers is a plus for me, but it also lets me experiment on my own.  I know what I want.  I know what other developers are doing with it, and I can whip out the Wacom (or, better yet, colored pencil and paper) and just let myself explore the possibilities.  I’ve been hanging out with a bunch of web “creatives” recently, and this is the language they use.  The posters of their office space run the gamut from photorealism to grunge to flat OEM (original English manga) style, with same 60’s psychedelic for a wine-and-Shakespeare festival on the far wall.

I’m sure you can run a good sized web business without this knowledge base.  But you’ll look like these guys.  I’ve sent these guys my resume’ because, you know, that’s what I’m required to do under the circumstances.   But let’s face it, these guys need help: four separate flash items on the home page, bad 2003 swirly headers, no alt tags on the title images, table based layout, and no grid sensibility at all.

This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com

Parsing HTML with regex summons tainted souls into the realm of the living.

If you hack HTML for a living, this will make you giggle.  And given that I’ve used regex in my tests to assert the presence of classes and objects in a page, I guess I’m guilty.

This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com

Today’s little snippet: Filtering a loosely coupled many-to-many relationship.  As revealed earlier,  I don’t really “get” the difficulty with many-to-many relationships.  I don’t even get the difficulty with signals; if you define the many-to-many manually, handling signals on it is trivial compared to trying to do it manually in one of the referring classes.

Today, I was working on an issues tracker.  There are two classes at work here, the Profile and the Issue.  One profile may be interested in many Issues, and obviously one Issue may be of interest to many Profiles.

This calls for a ProfileIssue table that stands independent (in my development paradigm) of both Profiles and Issues.   As I was working on a dashboard, I realized that one of the things I wanted was not just a list of the issues the profile was following, but also a list of the issues that the profile was responsible for creating.  As it turned out, adding that query to the ProfileIssueManager is trivial, but requires a little knowledge:

class ProfileIssueManager(models.Manager):
    def from_me(self, *args, **kwargs):
        return self.filter(issue__creator__id = self.core_filters['profile__id'])

The secret here in knowing about the core_filters attribute in the RelatedManager.   It contains the remote relationship key that you can use;  calling from_me from profiles works, but calling it from anywhere else doesn’t.  The IssueRelatedManager won’t have a profile_id and this will blow up.  That’s okay; using it that way is an error, and this is a strong example of Crash Early, Crash Often.

I can here some of you cry, “Now why, why would you need such a thing?” Well, the answer is pretty simple: templates. Having one of these allows me to write:

<p>Issues tracked: {{ profile.issues.count }}</p>
<p>Issues created: {{ profile.issues.from_me.count }}</p>

And everything will work correctly.

This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com

If you’ve created Django Application A, and then Django Application B, it is acceptable (and even sometimes necessary) for Application B to reference Application A.  The canonical example is Django contrib.auth; everyone references that beast.  It is not acceptable for you to go and edit Application A to reference Application B.  That is officially Doin’ It Wrong.

In a smarter world, you will never use a Django ManyToMany field.  You will create an individual class referencing both objects of the many-to-many relationship.  You will inevitably need more smarts than a mere two-column table, and a separate class, however small and insignificant, will provide both self-documentation and a chance to define the __unicode__() method for administration. Django is smart enough to hook up the relationships under the hood.

Unit testing is goddamned hard when your application is married to FacebookConnect.  A smarter relationship uses the SocialAuth layer, with additional proxies for information and posting handlers.  That way, not only can your application send updates to Facebook walls, but it can also update its activity on Twitter, and allow authentication via Google, and so on.  By using the SocialAuth layer, you can create a pseudo-layer that handles testing.  You’re still beholding to testing the SocialAuth stuff yourself.

If you’re using SocialAuth, push all of your user-related smarts into the UserProfile object, and always refer to it.  Build your UserProfile object to own the proxy to the user’s authenticated relationships with social media.  After login, leave the user alone!  Better yet, use middleware to attach the profile to the request object automagically if and when it’s present, and live with it.

This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com

One of the nifty things that Django provides is the
{% url backreference %} syntax, which allows
you to name the targets in your list of URL objects and then refer to
them by an explicit name. You can sometimes use the function name
instead, and Django has a way of turning the function name back into
the URL. It works fine as long as the signature of the backreference
and the signature of the function match.

It’s very nice for RESTful interfaces. But what about AJAXy webpages?
AJAX is all about D(X)HTML and the rendering and animation of user
interfaces in a broser, and there’s a lot of Javascript that comes
along with all that HTML and CSS. And embedded AJAX often comes with
its own set of URL calls. I mean, seriously, what if you want to write
something like this:

<example.js>=
$.getJSON(
"{% url results %}", {},
   function(resp) {
   $("#resultswrapper").html(resp.results);
});

Here, I want to replace the string “url results” with the url
that returns the results and shoves their visuals into the
“resultswrapper” HTML object, whatever it is.

You could do this in Django, making this a templatized object
and spewing it out every time. But often enough this URL
never changes during the lifetime of the program. This is
effectively javascript with a macro embedded in it that you want
substituted once, preferably at start-up. Well, I haven’t done the
start-up for you. But here’s a nifty little chunk of code that’ll do
URL reverse lookups in any static files in
your STATIC_DOC_ROOT directory (by the way, that
STATIC_DOC_ROOT setting is pretty useful for development, if you’re
serving static media out of your Django server, as devs frequently
do):

<addition to settings.py>=
import os
DIRNAME = os.path.normpath(os.path.dirname(__file__))
STATIC_DOC_ROOT = os.path.normpath(os.path.join(DIRNAME, 'static')) + '/'

And here’s the routine. Note that I’ve made it a Django command:
put it wherever you want and use it wisely:

<rendertemplates.py>=
from django.core.management.base import NoArgsCommand
from django.core.management.base import CommandError

from settings import STATIC_DOC_ROOT
from django.template import Template
from django.core.urlresolvers import reverse

import os
import os.path
import re

re_walker = re.compile(r'\.tmpl$')

class Command(NoArgsCommand):
    help = ("Run a series of templates through the Template handler to produce "
            "(semi) static files.  This is mostly useful for javascript "
            "handlers with Ajax calls in them that only need the urls "
            "defined when the application is first built or starts running.  It "
            "allows developers to use the {% url somethingorother %} syntax inside "
            "Ajax handlers without burdening the application at runtime.")

    def handle_noargs(self, **options):
        paths = [os.path.join(STATIC_DOC_ROOT, path[0], filename)
                 for path in os.walk(STATIC_DOC_ROOT)
                 for filename in path[2]
                 if re_walker.search(filename)]

        for fn in paths:
            fn_out = re_walker.sub('', fn)
            open(fn_out, 'w+').write(Template(open(fn, 'r').read()).render({}))

It’s not perfect (hey, I wrote it in about 20 minutes, mostly to
fix this problem in a quick and dirty fashion. Given that I didn’t
know how the innards of the Template class worked, and have never used
the new os.walk() function, this was pretty good.

As always, I’ve provided the source code for this.

This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com

So, remember my comment about unit testing yesterday?  This is what it looks like today. Here’s the features page:

Feature: Login
  In order to use the system
  As a customer
  I want to log in

  Scenario: Access page
    Given I am at the login page
    Then the page title should be "SecretProject"

  Scenario: Log in
    When I log in as "username" password "redacted"
    Then the page title should be "SecretProject - Project List"

And here’s the steps:

Given 'I am at the login page' do
  @browser.goto @options[:address]
end

Then /the page title should be "(.*)"/ do |title|
  @browser.title.should == title
end

When /^I log in as "([^\"]*)" password "([^\"]*)"$/ do |arg1, arg2|
  @browser.text_field(:name, 'username').set(arg1)
  @browser.text_field(:name, 'password').set(arg2)
  @browser.button(:xpath, "//input[@value='Login']").click
end

While I’m not entirely sold on the COBOL-esque nature of the unit tests, I respect the way cucumber makes you think about what you’re doing and generate scenarios and codify the steps to fulfilling those scenarios, all the while working well within the context of things like WATIR, Matchy, and so forth.

This entry was automatically cross-posted from Elf's technical journal, ElfSternberg.com