This article is cross-posted at Vox Product.

Today we’re announcing a new project we’ve been working on at Vox Media: Autotune, a centralized management system for charts, graphics, quizzes, and other tools. We built the 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’s 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:

1. You log in to create a project.
2. Choose which blueprint you want to use (e.g. a chart, a quiz, an image slider, or whatever else you can dream up).
3. You plug in the relevant data required by the blueprint. (e.g. a title, a data source, a theme, an image).
4. Publish and grab your responsive embed code.

Autotune in action!

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.

We wrote a tutorial on how to get Autotune running on your computer.

The Rails app handles storing stuff in a database, running shell commands against blueprints and projects and presenting a JSON API. The front-end is a JavaScript app built using Backbone.js, Bootstrap, and Alpaca.

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 to Alpaca. 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 project wiki.

We’ve made a few example blueprints that you can use now, and we’ll be open sourcing more as we go: keep an eye on the project wiki for more!

Importing an existing blueprint is as easy as copying and pasting the blueprint’s git url.

Getting started with a blueprint import

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: Mad Max before and after shots show what’s real and what’s fake

• 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 I 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.

Is there anything else you wish we had told you about Autotune? Let us know or add it to our documentation.

• Share on Twitter
• Share on Facebook