Welcome to my blog-site Platypus Innovation.

The platypus caused consternation, shattered existing categories. It's existence was undeniable, but how should taxonomic theory be adapted to accommodate this uncomfortable fact?

This blog is also hard to classify. It loosely follows the interests and activities of Winterwell Associates, but it also includes personal material. Topics are likely to range from business affairs to new media via abstract mathematics.

One purpose of this site is to test out some of Winterwell's web technology. This site will sync with my SoDash account, which unlocks some rather unique features, though you're unlikely to encounter them during normal browsing.

Where will this blog go? From humble acorns, great oaks grow. But what if we've planted peanuts by mistake? Or genetically modified acorns that will turn into Evil Oaks? Only time will tell.

Javascript/html templating: underscore.js for the win

Man cutting steel with a template (cc) Washinton State Dept of Transport

After experimenting with Javascript templating libraries, we decided to use underscore.js. It scores over JQuery, Moustache and others in having a very clean and simple relationship between templating and normal code.

Underscore templates provide spaces where you can drop into javascript code - that's all they do, but it works better than trying to do more. Crucially, this gives you a lot of freedom - the full freedom of javascript.

For example, here is a simple loop using underscore:

   <% for(var i=0; i<3; i++) print("

Line "

+i+"
"); %>

That middle section isn't the prettiest, but it's something every web developer should already understand -- and know how to write.

Compare this with the approach taken in JQuery templates:

   {{each}}
      

Line $i

   {{/each}}


This looks a little bit nicer -- but what are these new magic {{}} tags? Plus we need to pass in the list `[{i:1},{i:2},{i:3}]` in order to use it. And we have less ability to build richer more complex templates.

Hence, by taking a simpler code-based approach, underscore.js templates actually end up being more widely editable and more powerful.

Lessons for code documentation from product design?

Book sculpture by Daniel Lai, “Kenjio”

Good documentation is hard to do. It's a balancing act: It should be short yet clear. And of course, you don't want to spend too long on it.

I try to keep 2 high-level questions in mind, and write notes as I go which answer these:

1. What should a user of a system / class / method know?

This guides writing of javadoc and higher-level documents.

A "user" here is a developer who will call on the class/method, but won't look inside it. E.g. if you code in Java, then you're probably a user of java.util.List, and their (good quality) javadoc is aimed at you.

This user wants to understand: The purpose of a class/method, the inputs, the outputs/effects. Where it fits in the application's life-cycle.

2. What should a future developer who will edit the code of that system / class / method know?

This second "user" wants a few more details: Design choices & reasons, a summary for complex bits, any dead-ends to avoid. This last -- making notes on dead-ends and misadventures -- is especially useful when you return to old code & wonder why-did-I-do-it-that-way?

At each level, think about the person reading your documentation -- How have they got here? That is, what do they already know, and what might be strange to them? What are they trying to do? What do they need to know to do that (safely & well)?

Essentially, let's take the ethos of user-centred design -- and apply it to documenting code, by thinking of the developer as a form of user, and documentation as a product.

There are no AAA databases

It's a mistake to believe absolutely in uncertain things. That's one of the lessons of the financial crisis. Uncertain loans were dressed up as triple-A reliable assets, but it turned out to be wishful thinking.

Dice bag (cc) KaptainKobold@Flickr

I see similar practices in databases and business intelligence.

We all know that databases contain errors. The errors come from many sources: data is mis-entered, or it was accurate but people move on, or the database schema was changed, but not all the data was correctly updated, or two databases are merged, but the join is dodgy: same name doesn't always mean same person. I've yet to encounter a database that didn't contain errors.

Everyone knows this. And yet people build business processes that assume the database is 100% correct. Even best practice in data analysis is only to try and limit errors entering the system -- but once they're in, the mistakes can run free.

In business intelligence, we see claims that everything can be measured. Claims that are plausible & we'd like to believe. All too often it's over-confidence and over-selling.

Accepting uncertainty does not mean giving up on measurement. It just means accepting errors are part of measurement. Once we accept that, we can deal with it. We should estimate the things we cannot directly & accurately measure. But remember that is an estimate. And know how good that estimate is, and how much that affects your decisions. There are cases where the-right-order-of-magnitude is fine, and others where even 99% accuracy isn't good enough.

It's especially important to know the blind-spots in your KPIs -- the things you can't properly measure. And there are always blind spots.

Anyone who promotes KPIs and ROIs without talking about errors is selling something unreliable. It's easy enough to hide uncertainty & inaccuracy - but you pay the cost down the line with interest. Remember the AAA sub-prime loans -- not all that glitters is gold. We ignore uncertainty at your peril.

The salesmen of over-confidence cannot have it both ways: if data is important, you'd better be honest about its quality.

Geocoding Twitter: Who cares about New Zealand?

Geo-coding is where you take descriptions of a place -- such as the location people give out on Twitter -- and work out where on Earth it actually is.

Geo-coding is not an exact science. E.g. "Cambridge" could refer to a city in the UK, or one next to Boston in the USA (and oddly, both cities are home to world-class universities). And that's the easy stuff. Twitter locations can be... interesting -- such as "wherever there is dancing", or "city of purple".

So geocoding software can be forgiven for making occasional mistakes & odd choices. Here are some we've found:

Heaven is in Iran, but Paradise is in the USA.
Iran also counts as far far away.
Reality is in India
Gun Shaped State is Oman, as is Somewhere Yu Aint! (I suppose there's a kind of logic here-- for most of us, Oman is somewhere we aren't).
Wonderful Island is Taiwan...
...but Whore Island is somewhat cruelly identifed as Iceland
Atop of a Whovian Bum is in Azerbaijan

My favourite malapropism:
Who cares? and Who knows? mean you're in New Zealand

NB: We currently use a mix of Google, Yahoo & Twitter geocoders (each of which has it's own strengths and weaknesses). The examples above come from one of those three. It's usually Google -- who have the largest most varied coverage -- for the random. We are developing our own in-house geocoder based on Open Street Map data.

Spam, spam, lovely spam

This comment was such a great piece of spam, we had to publish it (minus the url).

Do you have а spam isѕue оn thіs ѕite;
I also аm a blogger, аnd Ι wаs wanting to knoω your ѕіtuation;
many of us hаve developeԁ some nicе mеthods
and wе агe looking to trade strаtegіes
ωith other folks, bе suгe to shoot me an emаil
if іntereѕtеd.

Нere iѕ my homеpagе viagra

Javascript Enums

Enums are a useful way to handle a set of constants. They protect against typos and bad-values, help to spot missed cases, and make refactoring a lot safer.

Javascript does not have enums. So how can we get the same benefits?

Enum.js is a simple class which gives you enum-like behaviour.

Example: Instead of writing e.g. if (sibling == 'BROTHER') ... throughout your code, write Sibling = new Enum('BROTHER SISTER'); then use if (Sibling.isBROTHER(x)) ....

Here's the Enum.js code as a gist