Five Ways to Optimise the Journey to ‘Hello World’

Every week, usually on Friday, the JavaScript Weekly and HTML5 Weekly newsletters drop into my inbox. And every week I scan through the list of five or six new libraries or frameworks, think “that sounds cool”, and on a good day I’ll try one or two of them out for a few minutes.

With so much new stuff popping up every week it’s critical that getting started with a new tool is easy and frictionless – or to put it another way, the “Time to Hello World” figure needs to be as small as possible.

How long does it take a typical developer to get something up and running after deciding to give your library a try? If it’s more than five minutes, I’d suggest that you’re dead in the water.

Many frameworks already do a great job of this. AngularJS and KnockoutJS stand out for having a live example sandbox right on the front page, meaning a curious developer doesn’t even need to download anything to start playing around. Here’s a new HTML5 game framework, which devotes half of its landing page to a four step quick start guide.

The front page for Google’s Play Framework has a prominently embedded screen-cast to walk you through building your first application. This is OK, but I find that repeatedly playing a few seconds of a video and then switching to a terminal or IDE to replicate the steps and back again can be quite a disjointed and frustrating experience. We can do better.

At Caplin we have the luxury of not needing to make our journey to “Hello World” particularly smooth, because our engagements almost always involve Caplin developers working with our clients to start a project. The rough edges and unintuitive aspects of setting up our technology stack can be smoothed over by having one of our experts do it, or at least talk somebody through the process. Still, just because we’re not directly competing with open source frameworks doesn’t mean that we shouldn’t try to make the developer’s initial experience much better. First impressions count, after all.

For our hack day I decided to imagine that our entire technology stack was free and open source, and evaluate it from the point of view of a curious developer who wanted to build a simple web application with real-time streaming data. It was very apparent that our framework is poorly set up for this sort of use case, and I was able to make a number of changes that improved the developer’s initial experience of the Caplin framework significantly. I’d like to share some of the quick wins I stumbled across, which might help you improve the “Hello World” experience for your own applications.

1 First things first, you need a single download. The Caplin stack is made up of a number of components – Caplin Trader for building the front end, our streaming server Liberator, various Java libraries and APIs for integrating with external systems, and more. You don’t want the user’s first experience of your framework to be trying to put together a jigsaw of unfamiliar components. Bundle it up instead!

2 Don’t make the user jump around between different tools. The framework should present a single access point where all commands and tasks are run. To build a Caplin application you currently need to use three different command line tools – one for creating and serving the front end, one for creating the skeleton for the back end, and one for serving the back end components. I was able to improve things by creating simple BladeRunnerJS plugins that called into the two back-end related tools, so that the user could set up and run the full stack from one terminal rather than three.

3 The user should be able to build their first application without ever having to leave their development environment to consult external documentation or tutorials. I was able to achieve this by turning the process into a sort of breadcrumb trail where the conclusion of each step prompts the user what to do next. You can get creative with the location of these prompts, for example, my process went something like this:

• After unzipping the kit there is a README file that tells the user to open a command prompt and run “./brjs create-app MyApp” to get started.
• I hacked the create-app task so that when it finishes building the skeleton for the app it prompts the user to open the project folder in their IDE and look at the main App.js file.
• The main App.js file has a comment at the top that tells the user to run “./brjs serve” to start up a web server that hosts the app.
• After running “./brjs serve” a prompt appears in the console that tells the user to open a browser and navigate to http://localhost:7070 to see their application running.
• I changed the auto-generated index.html that the user will see in their browser so that it tells the user what to do next – go back to the console and run “./brjs create-backend MyApp” to set up a back end for sending streaming data into the app.
• After running this command, the user is prompted to have a look at the newly generated MyAppDataSource.java file, which is where they start writing their back end code. This file contains a comment telling the user what to do next, and so on.

The goal is to always put a helpful prompt in the place where the developer would naturally go next anyway. It could be a message in the console after running a command, it could be a comment in some newly auto-generated code, it could be part of a web page. But you never want to drop the thread and leave the developer wondering what to do next. For example, if your framework generates a web application and when the user loads it up in a browser it just says “Congratulations, you created an app” then you’re missing a trick – it should tell the user where to go next.

4 Don’t force the user to learn anything technical about how the framework works unless they really need to know. The first thing they want to do is build an app. It may well be the case that there are many pieces of middleware at work under the hood, but all of that should stay out of the way until the user has a need to understand it. There is always time later on to dive into the technical details of a framework, but you need to get the user invested in your product first – if they have to read a load of documentation to understand how all the technical components fit together before they can build anything, they are likely to give up.

5 Generate as much of the boilerplate as you can, to reduce the amount of code the user has to write. A Caplin application involves building a webapp which subscribes to streaming data and renders it on the page. I tried to abstract the user away from writing low-level message handling code by requiring them to simply spec out the data they want to send and receive in a properties file. Using this file as input I wrote a plugin that used the Java port of Handlebars to auto-generate the required front end and back end code for sending and receiving the data. I was pleasantly surprised by how much of the grunt work could be automated by asking the developer to provide a logical model of what they want to achieve rather than asking them to write code.

By the end of the hack day I had managed to wrestle the Caplin stack into a single download with enough plugins, code generators and helpers to bootstrap a simple “Hello World” webapp with streaming data in less than three minutes. Hopefully some of these enhancements will make their way into the product soon, and you’ll be enjoying a much better getting started experience.