Read on and leave a comment
or return to our portfolio.

Posts in the ‘Fun’ category

7 Aug 2013

by Dave

Writing Documentation using Grunt and Jekyll

Running a startup is a lot of work. All manner of tasks constantly compete for the team’s attention mandating a careful dance to keep on top of everything. We haven’t nailed all the footwork to this dance yet, but we have learned that choosing the right tool for each job can drastically simplify the choreography.

We recently rewrote a large portion of Myna in the march towards version 2 of the platform. Most of the customer-facing software – the dashboard, client libraries, HTTP API, and so on – were completely new and required new documentation. Our existing help pages were in need of an overhaul, so we decided to move them out into their own project using a build system based on Grunt and Jekyll.

The new documentation is still a work-in-progress – you can watch its evolution on the Myna website and its repository on Github (yes, it’s open source – another experiment we’re trying). We’re really happy with the way it’s all working out, so we’ve published the build system as a separate project that you can use to bootstrap your own documentation. Go forth, fork, and profit!

Why Jekyll?

Our old documentation was implemented as a set of templates in the Play 2 web app that runs our marketing site and original customer dashboard. Publishing the app requires a PhD in SBT, Mongo and Redis, and if you’re writing documentation on the train (as we are prone to do) it isn’t uncommon to have your plans abruptly terminated by one of SBT’s frequent unavoidable urges to download the whole internet (unadvisable in the middle of signal-free rural England).

We considered moving to a CMS such as WordPress, but our support team are all developers with their own preferred editors and IDEs. Forcing them to write documentation (painful) in a tiny WYSIWYG editor embedded into a web site seemed like torture. Also, CMSs require internet connections… it kinda goes with the territory.

Grunt and Jekyll, in contrast, run completely offline, and have a number of other advantages too. Plugins like grunt-contrib-watch provide instant previews via Livereload, and Jekyll’s syntax highlighting (provided by Pygments) can highlight any syntax you throw at it (including, to my amazement, HTTP).
Jekyll isn’t completely perfect for the job. We had to work around a few issues. Fortunately, none of them proved insurmountable:

Versioning

We’ve run into versioning problems many times before, some requiring some pretty serious workarounds. In fact, versioning issues are pretty much endemic across all software development platforms. In this toolchain we’re relying on lots of components: Grunt, five Grunt plugins, Ruby, and Jekyll. Fortunately, versioning is pretty much a solved problem these days: NPM and Bower are great package managers for Node, and Bundler normalizes not only the version of Jekyll we’re using, but also the version of Ruby itself.

Static Assets (Say “NO” to Plain CSS)

I may catch some flack for this, but CSS is a silly language riddled with missing features and bizarre design decisions. No way are we going to battle with a new documentation project without tools like Less CSS and Twitter Bootstrap to support us. And if we’re compiling and minifying our CSS, we might do it for Javascript as well. Jekyll doesn’t support support for either process out-of-the-box.

One way of solving these issues would be to use Jekyll plugins – there are many candidates available on Github. However, we prefer to use Grunt for this kind of thing, running Jekyll via grunt-exec and Bundler, and using grunt-contrib-watch and grunt-contrib-connect for preview functionality.

Content Navigation

Jekyll has built-in support for cataloguing and paginating blog posts, but it can’t natively generate navigation for a hierarchical documentation site. Fortunately, this was easy to work around with a couple of custom plugins: one to create a table of contents for the sidebar, and one to generate next and previous buttons at the bottom of each page.

Authenticating Users

The main navigation bar on Myna changes when users log in. Ideally we want like to keep this consistent across the main web site, the blog, and the documentation. Our solution is to built a small Javascript app to monitor the user’s login details and rewrite the navbar on demand. This is a work-in-progress project and it’s not part of the Github repo above.

Conclusion

If you like the idea of writing documentation in Markdown, you can get started in two minutes by cloning our  Github repo  and following the instructions in the README. We’d love to hear from you if you find our system useful, and we welcome pull requests with improvements.

Posted in Code, Front page, Fun, General, Javascript, Myna, Web development | No Comments »

1 Sep 2011

by Noel

UU and You: Learn Some Opa

We want to try something a bit more interactive with Untyped University, our preteniously titled training program. Instead of just posting papers to Mendeley we’re going to hangout on G+. This should allow for easy discussion with our peers, which is to say: you.

For this session we’re going to hack on Opa. Normally we read through a paper, but we think hacking will work better over the medium. The goal is not (necessarily) to write something useful in Opa but rather to understand it’s model for web development. We’re not seeking to advocate Opa, nor are we experts on the language.

As G+ doesn’t yet support organisations, get in touch with me (email noel at untyped, or message Noel Welsh on G+) and ask to be my UU circle. We’ll be online on Friday 9 Sept from 13:37PM (+1 GMT), and will invite everyone in the circle to the hangout. See you there!

Posted in Code, Fun, Functional Programming, Web development | No Comments »

27 May 2011

by Dave

Friday fun with Scala syntax

It’s Friday – time to kick back and relax with two fun Scala programs we put together for your amusement.

Scala has a pretty flexible syntax (although not as flexible as Racket’s, of course) that makes it popular amongst proponents of DSLs. Not all DSLs have to be serious, however, as I’m about to prove.

First up is Noel’s original concept – proof of his love for DSLs, expressed in purest code:

 class A(num: Int) { def Scala = "It's s" + ("o" * num) + " much fun!" } object I { def <(num: Int) = new A(num) } I <3 Scala // ==> "It's sooo much fun!" 

Second is a simpler work that I call “The Startled Lolcat”:

 object O { def o = "What has been seen, cannot be unseen." } O.o // ==> "What has been seen, cannot be unseen."

Posted in Code, Fun, Scala | No Comments »

24 Jan 2011

by Dave

Smooth Scrolling for Mobile Safari

I recently wrote a jQuery plugin to do some smooth scrolling on the iPad, and I thought I’d share the code with everyone.

The effect you get is very similar to the iOS home screen. The user touches the screen and drags to scroll. Releasing the screen causes it to spring to the most appropriate page based upon the last dragging position and speed.

Gurus of front end development tell us that pretty much the only way to get smooth transitions on the iPad is to use 3D CSS transforms. After experimenting with jQuery animations and 2D CSS transforms, I pretty much concur: jQuery animations yield one or two frames per second, and 2D CSS transforms aren’t much better. 3D CSS transforms, on the other hand, are hardware accelerated and smooth as silk.

You can get the code from this Gist on Github (contributions and enhancements welcome). Use it with the following HTML:

 <div id="viewport"> <div>First page</div> <div>Second page</div> <div>Third page</div> </div> 

and the following Javascript:

 $("#viewport").scrollpane(); 

There’s a demo of it in action here. A couple of notes:

  • Because this hooks into touch gesture events and CSS3 3D transforms, it’ll pretty much only work on iDevices and possibly other Webkit-based tablets.
  • It works horizontally and vertically, but I’d recommend only using it horizontally in a regular web page because it interferes with Safari’s natural screen bounce. I had the benefit of a working on an offline brochure where the web page never scrolls naturally. In this environment the plugin really shines. If you are interested in doing something similar, take a look at the iPad app Delivery Site, which lets you customise various things like this.
  • There are a couple of options you can tweak to affect things like dead-zones before a drag will trigger a page transition. See the top of the source code for details.
  • When the first 3D transform is added to a page, Mobile Safari seems to transparently install an OpenGL panel to handle the effects. This causes a rendering glitch that’s just faintly visible if you’re paying attention. The plugin works around this by setting an identity transform on the scroll component on page load. Webkit is presumably frugal about 3D-ification for a reason, so you may find your web pages take more memory and CPU resources with this plugin active than without.
  • Really large (read “many-page, full-screen”) scroll panes can be very heavy on the browser. This is presumably due to the overhead of creating a texture buffer to 3D accelerate the transitions. I’ve managed five-page full-screen scrolling transitions without problems, but your mileage may vary.

Posted in Code, Front page, Fun, Javascript, Web development | No Comments »

27 Oct 2010

by Noel

Untyped HQ Number Two

We’ve moved! A few weeks ago I submitted by dissertation, which means I’m going to spend a lot more time at Untyped HQ in the future. This created a bit of a jam at our current office, so over the last weekend we shifted a few metres down the hall to a bigger room.

If you hang out in certain circles you’ll have recently spent some time eyeballing 37Signal’s new office and those of Yandex.ru. We don’t have the empty minimalism of 37Signals, or a blue thing with lots of pipes, and we forbid cheating pullups but it’s a pretty nice place none the less. See for yourself. If you like our style you can get the official Untyped desks in over 25 countries. Just remember, it’s birch, not beech!

Posted in Fun | No Comments »

6 May 2010

by Noel

Covering the Election

Today is the closest and most interesting general election in the UK that I can remember. This blog isn’t the place to talk politics, but while reading the manifestos of the three major parties I was struck by their design, and particularly the design of their covers, and I’m going to share some thoughts today on this topic. I think it’s interesting to look at the message the each party is trying to convey with their design and in particular how they all, for me, got it wrong. In alphabetical order, here they are:

The Conservatives

Gold lettering on a blue cloth binding. I knew I’d seen this before but it took a while before I remembered where: my parent’s old textbooks, which I used to leaf through as a child, had this kind of binding beneath their dust jackets. I looked through all my and my wife’s textbooks and didn’t find any the same. Add in the stuffy “Invitation” and to me this says old. Very traditional, very establishment, and very much at odds with the image of David Cameron, with no tie and top button undone, presented in the Tory advertising.

Labour

This is not a subtle cover. The illustration benefits from the fact the UK is a small country and most places look more or the less the same, so the patchwork fields will look like “home” to almost everyone. I’m a bit surprised the couple looks so white; I’d expect Labour to embrace diversity a bit more. However the whole feel of the cover is quite retro. The style of illustration and the rural setting (the UK is very urbanised) both seem to looking backward to me. I like the alliteration in the text. That blazing hot sun disturbs me; it looks more like a nuke going off than the gentle British sun I’m used to.

Liberal Democrats

It’s hard to say much about this cover, as it doesn’t say much to me. The repetition of “fair” is effective, and this is continued inside. The colours are washed out. This cover doesn’t really inspire any emotion in me; it looks more like an annual report than a manifesto!

Of the three I like the Labour cover the most, but as you’ve seen none of them really worked for me. This isn’t too surprising; major political parties must paint with such a broad brush that they cannot really address any small demographic. Now enough about the manifestos; go out and vote!

Posted in Design, Fun | No Comments »

6 Sep 2008

by Noel

Codeswarm

Codeswarm is a repository visualisation tool. It produces movies that show who is working on what throughout the lifetime of the repository. Although I find the movies quite pretty, to be honest I don’t get much useful information from them. Judge for yourself from movies of the PLT repository and the Untyped repository. Compare tothe Linux kernel for a more psychedelic experience.

Posted in Fun | No Comments »

25 Mar 2008

by Noel

Epic Lolz

Over Easter we insulated our roof. It was quite easy job, but I’m not going to write much about it as this post is entirely an excuse to show this picture:

funny pictures

No animal abuse was involved: he climbed up the ladder into the loft and stayed there until we moved him to put down more insulation.

Posted in Fun | No Comments »

4 Jan 2008

by Noel

Word of the Milieu: Flattline

Flattline |flatˌlīn| (verb).

To post a difficult problem, often syntax related, to the plt-scheme mailing list in the hope that wiser folk will solve it. For example: “I’ve gone nowhere on this macro in two weeks. I’m going to Flattline it.”

The term depends on an ambiguity between the medical term flatline, indicating a patient is dead (as in “he flatlined before we reached the hospital”), and the suggestion that one has a hotline to Matthew Flatt, the motive force behind the PLT Scheme implementation. Uses of the word that exclude either meaning are incorrect, so one should not say, for example, “I’m going to put a call on the Flattline”. One should also not expect Matthew Flatt to solve all of one’s problems.

Posted in Fun | No Comments »

7 Dec 2007

by Noel

ICFP 2007 In Fashion

Naturally no meeting of computer scientists would be complete without some mention of fashion. The satorial pinnacle of ICFP was easily claimed by Adrien Pierard who was rocking a bowler hat and pipe combo. I was pleased to find his hat was indeed sourced fromJames Lock & Co. I saw several Threadless t-shirts: The Communist PartyDark Side of the Garden, and Well This Just Really Sucks. (Follow the first link to Threadless, buy a T-Shirt, and I get $3.00 towards a tee. Follow the other links and I get nadda. Threadless is a great example of a business model that is only possible over the Internet. If you’re not familiar with them, check ‘em out.)

Computer scientists pay almost as much attention to their computers as they do to their clothing. From an informal survey of the conference Apple is continuing its rise in popularity amongst the geek crowd — the ratio of Mac to PCs was about 1:1. Of course a Mac is about as close to a fashion statement as a computer can come, so it isn’t surprising to see this adoption.

Posted in Fun | No Comments »