Today we're announcing a new project we've been working on at Vox Media: Autotune. We built this application to address the problem of reusability in our work. This project is open source and available to everyone.
As any news hacker knows, one of the most challenging requests we get is for "more of those things." We'll make a neat chart, visualization or map, which sees some success: our readers or reporters like it or maybe it helps tell a better story. You better believe other folks will come around asking for "one of those charts like on that one story."
One of the most difficult messages to communicate to our non-developer colleagues is how tricky "reusability" is. The common misconception is that once software is built, it can be reused. In reality, software is almost always built to accomplish a specific task in a specific context with no thought to how it might be reused.
It may sound as if this is a problem, a lack of foresight or a rookie mistake, but it is not. It is almost always a mistake to attempt to build reusable software from the start without taking the time to understand how it will be used and why. Working under deadline, building something for a specific story, is the worst time to try to anticipate how the code will be used in the future.
The goal of Autotune is to shorten the gap between building a one-off website or interactive graphic and building a reusable tool for generating many things.
What is Autotune?
In simple tech jargon, Autotune is a web interface for static site generators.
At Vox Media, we use the Middleman static site generator as the basis for all of our editorial projects: maps, charts, quizzes, story packages, brackets, etc.
Autotune allows us to keep Middleman as a core piece of our technology stack. We can build projects the same way that we always have, only we now have a very well-defined path to take a project from a simple one-off production to a reusable project blueprint.
For everyone else who doesn't work at Vox Media, Autotune is agnostic about how you build projects. It's built from the ground up to support any language and framework. Today it supports Ruby, Node.js, and Python blueprints. So you can integrate Autotune as part of your workflow and toolset without having to use Ruby.
A project blueprint for Autotune is simply a static site generator project in a git repository with some extra metadata describing the project and how to generate a form to provide the data needed to build the project. Autotune automates the steps a news developer would typically take to download a project, load new data into that project, and build and deploy that project to a public place.
How do you use it?
For an editor or reporter, Autotune works like this:
- You log in to create a project.
- Choose which blueprint you want to use (e.g. a chart, a quiz, an image slider, or whatever else you can dream up).
- You plug in the relevant data required by the blueprint. (e.g. a title, a data source, a theme, an image).
- Publish and grab your responsive embed code.
How does it work?
Autotune is built with Ruby on Rails and distributed as an engine. A Rails engine is just a fancy way to package a Rails application that doesn't include private addresses or authentication information.
When Autotune interacts with a blueprint, everything occurs in a Unix shell. When a new blueprint is added, Autotune reaches out and clones the git repo on the server and reads the autotune-config.json file. This file tells Autotune everything it needs to know about the blueprint: title, thumbnail, instructions, supported themes, etc. The key part of the config file is the form description.
When creating a new project from a blueprint, Autotune reads the form description from the config file and passes it toAlpaca. Once the project is saved, Autotune runs the build command in a shell, passing along all the project data. It is up to the blueprint to handle the incoming data and generate a folder full of static html and assets. This folder is then deployed to a configurable destination. All of the shell operations (git and build commands) are performed in asynchronous jobs, so the front-end can stay responsive and the build scripts can take as much time as they need to complete. The jobs are provided by Resque and Redis.
How do I implement it in my newsroom?
You can start using this in your newsroom today. The instructions are in the wiki.
We've made a few example blueprints that you can use now, and we'll be open sourcing more as we go:https://github.com/voxmedia/autotune/wiki/Example-blueprints.
Importing an existing blueprint is as easy as copying and pasting the blueprint's git url.
Once Autotune clones the repository, you are ready to create projects from it.
If you need some inspiration, here are some real-world examples of our blueprints being used on Vox Media properties:
Image slider: The Verge: Amazon Kindle Paperwhite review
Headline randomizer: The Verge: To Apple, Love Taylor Swift
Headline randomizer: Eater: Predict the next restaurant concept to hit Charleston
Data table: SBN: Opening 2015 recruit roster
Randomizer: The Verge: Ask the nearest hippie Antonin Scalia
How can you participate?
You can help Autotune grow by contributing features and fixes to the core platform as well as by creating new blueprints.
Don't know where to start? Pick something from our backlog of things we have planned for Autotune.
Making your one-off interactive or tool a blueprint is a great way to help others create more of those easily. To go from a static project to a blueprint, all you need is some code refactoring and a few new files that tell Autotune what inputs to gather and how to build the project. We've created a step-by-step tutorial to walk you through that process.