The Making of #learnchef

What’s the fastest way for a new user to go from zero to ‘converge’? – Bryan Hale

A few weeks ago, we launched the #learnchef campaign. #learnchef was designed to improve our content by helping more users successfully converge their first node. Although we saw a relatively large number of signups for Hosted Chef, only a small percentage of users were actually converging a node. Those who have been using Chef for some time will attest – there’s this “magical moment” when you successfully complete your first chef-client run. Suddenly, Chef begins to make sense and you are and eager to further explore the power of Chef and infrastructure automation. After some amazing feedback from our users via Office Hours, Twitter, etc, we identified the content area that needed some attention, and #learnchef was born.

Goals

#learnchef was established with a single goal in mind: What’s the fastest way for a new user to go from zero to ‘converge’? After a few planning meetings, it broke down to this:

1. Don’t show the reader any unnecessary information. Just enough Ruby. Just enough Chef. Just enough background to get the ball rolling.
2. Don’t introduce or mention features of Chef that aren’t necessary. Chef has so many amazing features that it can be intimidating for a new user. Let’s keep it simple. You don’t need roles, data_bags, or environments to converge your first node. Similarly, you don’t need Berkshelf, Librarian or knife-spork either.
3. Keep the reader on #learnchef. A common complaint about the Wiki was that information was scattered across Confluence or pointed to external sites and resources. Let’s keep everything under one roof.
4. Convergence can happen over a single lunch break.

Process

We identified a three step process:

1. Workstation Setup
2. Using Chef Repo
3. Converge

But we quickly hit a stumbling block on Workstation Setup – Windows? Mac? Linux? How could we make a single guide that encompasses all the different steps for the various operating systems? How could we present that information in a user-friendly fashion? A similar discussion quickly followed suit – omnibus or manual installation. Onmibus is definitely the easiest way to get started with Chef, but a user may want finer control over their local rubies on a workstation. We solved this delima with UI – tabs.

#learnchef allows you to “choose your own adventure”, which makes the process fun an interactive. It’s engaging and fun – try it out!

Screencasts

We finished the QuickStart Guide and then said “now what?” We learned that, for some people, following plain text is often difficult – especially in a tutorial. Coincidentally our Community Manager Nathen Harvey had started developing a collection of screencasts that lined up with the work I was doing on #learnchef. The projects merged and #learnchef screencasts was born. Just like #learnchef, the #learnchef screencasts are short, sweet, and to the point. Many of the videos are less than 2 minutes long!

Common Use Cases

We also recongized a gap that exists after your first converge. Where do you go from there? Thus the #learnchef Common Use Cases was born. They are a collection of typical use cases with Chef – like converting a Bash script or configuring NTP.

Social

Because learning is an interactive process, #learnchef comes complete with:

• IRC: #learnchef
• Twitter: @learnchef
• Email: learnchef@opscode.com
• Web: https://www.chef.io/training/tutorials

We realized that sometimes documentation just isn’t enough, especially when you hit a roadblock. That’s why, in addition to all the resources listed above, we also provide an easy way to reach a support representative:

During regular business hours, you will be connected to a support agent via Live Chat. We also encourge you to sign up for Chef Office Hours and Live Chat with an engineer.

Technology

People have been asking on Twitter and IRC, so I will briefly talk about the #learnchef technology stack. #learnchef was built using Middleman, which gave us all the benefits of a Rails app, like named paths, partials, and asset compression, but compiled into static HTML. Middleman also uses Tilt for templating, so we inherited support for Markdown, RDoc, ERB, etc. All our HTML layouts are written in Slim and the actual content is written in Markdown with some Custom Redcarpet Extensions for callouts and tabs.

The #learnchef source is not currently public, but it is scheduled for release in the future.

Looking Ahead

We are actively working on expanding the #learnchef program, especially the Common Use Cases and Screencasts. We are gradually moving outdated guides from the Opscode Wiki to #learnchef, as well as creating new guides to address a broader depth. We have some amazing things for #learnchef coming down the pipeline including real-time chat, more screencasts, and more fun!

If you’d like to see a specific topic covered, let us know! A ping on Twitter or an email will do just fine.