ALL THE THINGS
How (and Why) the jQuery Foundation Open-Sourced Our Web Designs And Content

Adam J. Sontag

ajpiano.com/jquery-allthethings

Once upon a time

docs.jquery.com

  • Let's crowdsource the documentation! Make it a wiki!
  • Everybody can help!
  • Translation: Anybody can spam!
  • Solution: Turn off user registration
  • Outcome: Nobody can help

Well, not nobody

  • Anyone who had an account still could use it
  • Admins could create accounts for new people…
  • …if new people could get in touch with admins…
  • …and not be spammers…

Unfortunately, this sucks for everyone:

So we realised some things had to change

  • API documentation should be structured
  • And it shouldn't be in a wiki

So we converted the docs to XML …

…and then pasted it into WordPress.

:(

This also sucks for everyone

Similar problems plague both Wikis and traditional CMSes

  • Requires special permission to access
  • Editing experience is subpar
  • Changes aren't tracked in version control
  • Volatile content lives in the database, needs to be backed up
  • No issue tracking
  • Wholesale duplication of templates/CSS across sites
  • There's only one live site: extremely conservative about features, no room for experimentation

Duplicating things twice is bad

but jQuery has about 20 websites

so duplicating things is bad bad bad bad bad bad bad bad bad bad bad bad bad bad bad bad bad bad bad bad bad

When things become unmaintainable, they cease to be maintained

We had to make a change.

So we did a SNAZZY REDESIGN

…in 2010

It turns out there is more to implementing a snazzy redesign across 20 sites than "having a comp."

Especially when you're trying to also solve all the other problems

How do other open source pr...oh!

Things That Work For jQuery Code

  • Local development
  • Version control
  • Public issue tracking

Things That WOULD Work For jQuery Content and Design

  • Local development
  • Version control
  • Public issue tracking

All Hands On Deck!

Anyone should be able to submit a fix or improvement, no matter how large or how small, to any jQuery web site, using their text editor of choice.

So we put it all on GitHub!

The content of each of the sites is stored in Markdown, HTML, or XML.

But wait, how does that get ON THE INTERNET?
(The answer may surprise you.)

WordPress!

But You Just Sa…

  • We had been working transfering Doug's original designs to a WordPress theme, because of features like theme inheritance and multisite install
  • It was going … OK, but it certainly wasn't elegant; we were using some custom node scripts to manually populate MySQL.
  • So we were also experimenting with other solutions that would achieve our goal of having versioned, open content, e.g., static site generators like nanoc

A Match Made in D.C.

The jQuery Board was having a meeting. We met Andrew Nacin at a meetup. He told us he knows a thing or two about WordPress, and could help us out. So could Daryl Koopersmith, who promptly hopped on a plane from San Francisco upon hearing what was afoot.

A few days later, we had jquery-wp-content*

jquery-wp-content

A custom WordPress "distro" that

  • contains a custom install script that automatically configures the multisite install
  • includes any necessary WordPress plugins
  • automatically delegates between local, stage, and live environments
  • has a parent/child theme setup that provides consistent structure and styling across all sites
  • is relatively easy for anyone to set up

No, but seriously, how does that get ON THE INTERNET?
(I guess I still haven't covered that)

Doing the grunt work

Those "custom node scripts" evolved into two grunt plugins that do most of the work

grunt-jquery-content

  • processes the Markdown, HTML, and XML in a content repo into HTML
  • applies syntax highlighting/table of contents

grunt-wordpress

  • validates the structure of the files built by grunt-jquery-content
  • synchronizes the posts and pages into a designated WordPress instance using XML-RPC
  • uploads/updates resources (images, downloads)

git'ing It Together

We use git web hooks to automate our deployments.

  • Whenever a commit lands in master of jquery-wp-content or any content repo, the staging environment (stage.*) is updated.
  • Whenever jquery-wp-content or any content repo is tagged with a semver, the live site is updated.
  • Protip: npm version is awesome

We don't use the wp-admin*

DEMO TIME

"Wow, that was awesome! How can I help?"
--You

Great Question!

  • File Issues
  • Make fixes and improvements to existing site content
  • Take the plunge, set upjquery-wp-content and work on design, content, or ANYTHING!
  • Check out our contribution hub for more information
  • Be present! Join us on IRC (#jquery-content on Freenode), follow projects on GitHub

"But what should I help with?"
--You

Another Great Question!

  • Every project has open issues — grab one!
  • New Learning Center is a great place to share your knowledge with others
  • Yes, the new Plugin Registry uses this stack too — help it grow!
  • Remember, no fix is too small!

Goals

  • Encourage active development
  • Increase collaboration and visibility
  • Lower barrier to entry
  • Create development, staging, and production environments
  • Simplify and automate deployment
  • Make working on docs and design "feel like" writing code
  • Create new ways to contribute to open source

write more lesser and get mucher