Untyping http://untyped.com/untyping Just another WordPress site Thu, 08 Aug 2013 10:51:13 +0000 en-US hourly 1 http://wordpress.org/?v=3.4.1 Writing Documentation using Grunt and Jekyll http://untyped.com/untyping/2013/08/07/writing-documentation-using-grunt-and-jekyll/ http://untyped.com/untyping/2013/08/07/writing-documentation-using-grunt-and-jekyll/#comments Wed, 07 Aug 2013 16:20:40 +0000 Dave http://untyped.com/untyping/?p=663 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.

]]>
http://untyped.com/untyping/2013/08/07/writing-documentation-using-grunt-and-jekyll/feed/ 0
Meanwhile, at Untyped HQ… http://untyped.com/untyping/2012/10/19/meanwhile-at-untyped-hq/ http://untyped.com/untyping/2012/10/19/meanwhile-at-untyped-hq/#comments Fri, 19 Oct 2012 15:28:04 +0000 Laura http://untyped.com/untyping/?p=453 … crickets

As you probably know, for the past few weeks, we’ve been concentrating hard on Myna. We’ve been accepted onto the Oxygen Accelerator program at Birmingham Science Park, Aston, so we’re hard at work setting up companies, opening bank accounts, and other such menial tasks.

In the land of Untyped, all we can see is myna birds.

In case you haven’t done so already, pop on over to the Myna blog, where you can keep up to date with the latest happenings (and anecdotes from life on Oxygen), or follow the Twitter account. Also note that Myna is still in free beta, so if you’d like to try it out, go ahead and sign up. All feedback is gratefully received – drop us a line via the Myna contact page.

Thanks, and have a great weekend!

]]>
http://untyped.com/untyping/2012/10/19/meanwhile-at-untyped-hq/feed/ 0
New site http://untyped.com/untyping/2012/08/28/new-site/ http://untyped.com/untyping/2012/08/28/new-site/#comments Tue, 28 Aug 2012 19:56:52 +0000 Dave http://untyped.com/untyping/?p=6 The portfolio on untyped.com was in need of some love, so we’ve redesigned the site and brought it up to date.

The new design is a lot simpler. We’ve combined the main page with our new portfolio and given each project its own distinctive look and feel. For example, the section for Myna mimics mynaweb.com, and the section on the Urban River Survey is based on the map of survey data around London*.

We should also give another round of thanks to Si Hammond, who came out with us to photograph our beloved Royal typewriter mascot against various Birmingham-based backdrops. We’ve got such mileage out of these photographs – they lend real character!

]]>
http://untyped.com/untyping/2012/08/28/new-site/feed/ 0
Myna for WordPress available now! http://untyped.com/untyping/2012/06/06/myna-for-wordpress-available-now/ http://untyped.com/untyping/2012/06/06/myna-for-wordpress-available-now/#comments Wed, 06 Jun 2012 19:57:45 +0000 Noel http://untyped.com/untyping/?p=8 Cliff Seal of Pardot has released v0.1 of his WordPress plugin for our web content optimiser, Myna!

Cliff’s plugin lets you test and optimise the content of your WordPress posts and pages. Why not try it on your web site?

]]>
http://untyped.com/untyping/2012/06/06/myna-for-wordpress-available-now/feed/ 0
The Circus is in Town http://untyped.com/untyping/2011/10/20/the-circus-is-in-town/ http://untyped.com/untyping/2011/10/20/the-circus-is-in-town/#comments Thu, 20 Oct 2011 19:59:34 +0000 Dave http://untyped.com/untyping/?p=11 Following a couple of late caffeinated nights, we are pleased to announce that our latest project, Bigtop, is finally set for beta release!

Bigtop is a collection of libraries for web developers. Included in the first beta release are:

  • Bigtop Routes – a library for creating type-safe bidirectional mappings between URLs and Scala code;
  • Bigtop Core – a library for generating and manipulating URLs and hyperlinks in a functional style.

Routes uses the HList-based approach to bidirectional pattern matching that Dave presented at Scala Lift-Off London 2011. There are versions of the library for use with LiftScalatra, and plain old Java servlets.

Check the Bigtop web site for a getting started guide, API documentation, and links to the code and Maven repository.

]]>
http://untyped.com/untyping/2011/10/20/the-circus-is-in-town/feed/ 0
Reading, Writing, and the REST http://untyped.com/untyping/2011/10/10/reading-writing-and-the-rest/ http://untyped.com/untyping/2011/10/10/reading-writing-and-the-rest/#comments Mon, 10 Oct 2011 20:00:34 +0000 Dave http://untyped.com/untyping/?p=13 I’ve just finished preparing the slides for my talk at Scala Lift-Off London 2011 next week. The title of the talk is A Route to the Three ‘R’s: Reading, Writing, and the REST. Here’s the abstract:

The mappings between URLs and code form an integral part of any web application. Many web frameworks help map from URLs to code, but the reverse mapping is often neglected, leaving developers to construct URLs via haphazard string manipulation. Furthermore, many frameworks do not match URLs in a type-safe manner.

Scala provides all the tools we need to address this problem in a more comprehensive manner. In this talk we will walk through the creation of Bigtop Routes, a bidirectional mapping library that is both type-safe and developer-friendly. We will pay particular attention to the ways in which Scala language features, such as flexible syntax, implicit conversions, and a touch of type-level programming, help to simplify the task at hand.

The slides and code samples are all available from my Github page. Skills Matter have posted a video of the talk on their web site.

]]>
http://untyped.com/untyping/2011/10/10/reading-writing-and-the-rest/feed/ 1
UU and You: Learn Some Opa http://untyped.com/untyping/2011/09/01/uu-and-you-learn-some-opa/ http://untyped.com/untyping/2011/09/01/uu-and-you-learn-some-opa/#comments Thu, 01 Sep 2011 20:03:24 +0000 Noel http://untyped.com/untyping/?p=15 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!

]]>
http://untyped.com/untyping/2011/09/01/uu-and-you-learn-some-opa/feed/ 0
What is Hacker News Worth? http://untyped.com/untyping/2011/08/30/what-is-hacker-news-worth/ http://untyped.com/untyping/2011/08/30/what-is-hacker-news-worth/#comments Tue, 30 Aug 2011 20:04:33 +0000 Noel http://untyped.com/untyping/?p=17

Twelve thousand hits, some thirty emails, and over a dozen new beta testers. That’s what happened when a blog post of ours spent ten hours on the Hacker News frontpage. It was definitely fun getting all that attention, despite the rush of traffic taking our little server off the web for a while. (Installing WP-Cache brought it back.)

Myna is the system described in the blog post, and we’re accepting beta users right now. If you’re interested in content optimisation on your website, and want better results than A/B testing will deliver, do take a look. Obviously getting this surge of traffic from HN is incredibly valuable to us. However I don’t have any suggestions for repeating the event: when I submitted the blog post to HN some months ago it disappeared without a trace. Certainly being active answering questions on HN helped keep it on the front page, and that position netted us a fairly steady thousand hits an hour.

If you’re one of the people who read our blog post, thanks for the interest! It’s very exciting for us to know that our idea for improving content optimisation resonates with so many people, and we’re looking forward to getting Myna out of beta and seeing where it takes us.

]]>
http://untyped.com/untyping/2011/08/30/what-is-hacker-news-worth/feed/ 0
Friday fun with Scala syntax http://untyped.com/untyping/2011/05/27/friday-fun-with-scala-syntax/ http://untyped.com/untyping/2011/05/27/friday-fun-with-scala-syntax/#comments Fri, 27 May 2011 20:05:40 +0000 Dave http://untyped.com/untyping/?p=19 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."

]]>
http://untyped.com/untyping/2011/05/27/friday-fun-with-scala-syntax/feed/ 0
The Future of VoIP Phone Configuration Interfaces http://untyped.com/untyping/2011/05/23/the-future-of-voip-phone-configuration-interfaces/ http://untyped.com/untyping/2011/05/23/the-future-of-voip-phone-configuration-interfaces/#comments Mon, 23 May 2011 20:06:59 +0000 Noel http://untyped.com/untyping/?p=23 We’ve recently completed a very fun and interesting job working on a new interface for managing VoIP phone systems. We have a VoIP phone, provided by Loho, who were also our client for this project. It’s great — we can forward calls to our mobiles, cart the phone around with us (plug it into a network connections and it just works), and it even emails us our voice messages. The only thing not great about our phone is the configuration interface. Luckily, that’s what this project set out to solve.

The brief was to implement an elegant online phone configuration system. Alex, Director at Loho, provided the vision. We provided two weeks of development time, which was enough to create a working prototype. Alex has asked us to not give away too many details about the system, but I can show you a few screenshots. First up, here’s the main screen:

The very stylish main menu of the VoIP administration tool we've built for Loho.

The very stylish main menu of the VoIP administration tool we’ve built for Loho.

Doesn’t give away much, does it? A bit more interesting is a detail of editing a configuration:

Also very stylish: editing the configuration of a voice menu

Also very stylish: editing the configuration of a voice menu

Here I’m editing a voice menu — one of those “Press 1 if you’re interested in giving us all your money” type things.

We think we’ve created a very nice system. Loho tell us they were overwhelmed with interest at a recent tradefair, suggesting we’re not alone in our opinion. While the interface is an important aspect of the work, the backend (which I can talk about!) is just as important. The main task was defining a data model to capture the rich feature set that Loho provide. This turned out to be very similar to designing a programming language and its intermediate representation. For example, we use a continuation-passing style representation to avoid maintaining a stack on the server side. Our representation distinguishes between tail calls and normal function calls to avoid excessive resource consumption on the VoIP side. Relational databases don’t do a very good job of storing recursive datastructures, like the AST of a programming language, so we used Mongo for the data store. In addition to its flexible data model, Mongo is web scale which has given us an immediate status boost at local programmer meetups.

The backend code is implemented in Scala and Lift. There are actually two interfaces to the service. One is the nice interface the users see, and the other is a REST interface that is called by the Asterisk AGI scripts that implement the VoIP functionality. The Asterisk system doesn’t handle all the functionality we represent internally, so the REST interface includes a small interpreter that executes intermediate steps till we arrive at something Asterisk deals with.

]]>
http://untyped.com/untyping/2011/05/23/the-future-of-voip-phone-configuration-interfaces/feed/ 0