Tags: codeforamerica

7

sparkline

Code refactoring for America

Here at Clearleft, we’ve been doing some extra work with Code for America following on from our initial deliverables. This makes me happy for a number of reasons:

  1. They’re a great client—really easy-going and fun to work with.
  2. We’ve got Anna back in the office and it’s always nice to have her around.
  3. We get to revisit the styleguide we provided, and test our assumptions.

That last one is important. When we provide a pattern library to a client, we hope that they’ve got everything they need. If we’ve done our job right, then they’ll be able to combine patterns in ways we haven’t foreseen to create entirely new page types.

For the most part, that’s been the case with Code for America. They have a solid set of patterns that are serving them well. But what’s been fascinating is to hear about what it’s like for the people using those patterns…

There’s been a welcome trend in recent years towards extremely robust, maintainable CSS. SMACSS, BEM, OOCSS and other methodologies might differ in their details, but their fundamental approach is pretty similar. The idea is that you apply a very specific class to every element you want to style:

<div class="thingy">
    <ul class="thingy-bit">
        <li class="thingy-bit-item"></li>
        <li class="thingy-bit-item"></li>
    </ul>
    <img class="thingy-wotsit" src="" alt="" />
</div>

That allows you to keep your CSS selectors very short, but very specific:

.thingy {}
.thingy-bit {}
.thingy-bit-item {}
.thingy-wotsit {}

There’s little or no nesting, and you only ever use class selectors. That keeps your CSS nice and clear, and you avoid specificity hell. The catch is that your HTML is necessarily more verbose: you need to explicitly add a class to whatever you want to style.

For most projects—particularly product work (think Twitter, Facebook, etc.)—that’s a completely acceptable trade-off. It’s usually the same developers editing the CSS and the HTML so there’s no problem moving complexity out of CSS and into the markup templates. Even if other people will be entering the actual content into the system, they’ll probably be doing that mediated through a Content Management System, rather than editing HTML directly.

So nine times out of ten, making the HTML more verbose is absolutely the right choice in order to make the CSS more manageable and maintainable. That’s the way we initially built the pattern library for Code for America.

Well, it turns out that the people using the markup patterns aren’t necessarily the same people who would be dealing with the CSS. Also, there isn’t necessarily a CMS involved. Instead, people (volunteers, employees, anyone really) create new pages by copying and pasting the patterns we’ve provided and then editing them.

By optimising on the CSS side of things, we’ve offloaded a lot of complexity onto their shoulders. While it’s fair enough to expect them to understand basic HTML, it’s hardly fair to expect them to learn a whole new vocabulary of thingy and thingy-wotsit class names just to get things to look they way they expect.

Here’s a markup pattern that makes more sense for the people actually dealing with the HTML:

<div class="thingy">
    <ul>
        <li></li>
        <li></li>
    </ul>
    <img src="" alt="" />
</div>

Much clearer. But now the CSS looks like this:

.thingy {}
.thingy ul {}
.thingy li {}
.thingy img {}

Actually it’s probably going to look more complicated than that: more nesting, more element selectors, more “defensive” rules trying to anticipate the kind of markup that might be used in a particular pattern.

It feels really strange for Anna and myself to work with these kind of patterns. All of our experience screams “Don’t do that! Why would you that?” …but in this case, it’s the right thing to do for the people building the actual website.

So please don’t interpret this as me saying “Hey, everyone, this is how you should write your CSS.” I’m not saying this is better or worse than adding lots of classes to your HTML. If anything, this illustrates that there is no one right way to do this.

It’s worth remembering why we’re aiming for maintainability in what we write. It’s not for any technical reason. It’s for people. If those people find it better to deal with simplified CSS with more complex HTML, than the complexity should be in the HTML. But if the priority for those people is to have simple HTML, then more complex CSS may be an acceptable price to pay.

In other words, it depends.

Cake for America

The Code for America project at Clearleft was fun for everyone involved. And because the code for the site is open to anyone to contribute to, the fun didn’t have to stop when the project officially wrapped up.

Because of her experience with front-end styleguides, we had hired Anna to work as a front-end developer on the Code for America project. But even when she was officially discharged of her duties, she decided to keep contributing to the public codebase.

For this service above and beyond the call of duty, Mike rewarded her in the time-honoured way: cake! In this case, the cake was inspired by the unofficial project theme song we blasted out every morning in the Clearleft HQ.

Anna's cake Anna's cake

Launching for America

I’ve already written a bit about the process of working with Code for America, which has been an absolute pleasure. Just today, Jon described it as “the closest thing to a dream project.”

I concur. Not only did the client communication work out really well, but their willingness to share the pattern library we put together warms the cockles of my heart.

When Clearleft’s part in the project officially wrapped up, I wrote:

It’ll be a while yet before the new site rolls out.

That was exactly one month ago.

The new Code for America website went live last Friday.

I’m impressed! That’s a pretty short timescale to rebuild a fairly large website, not only changing the front-end codebase, but also switching out the back-end stack as well. They must’ve been working flat out.

I’ve worked on projects in the past where my initial excitement at the project’s wrap diminished as the site launch date slipped further and further over the horizon of the future. It isn’t unusual to have a gap of many months between the end of Clearleft’s time on a project and seeing the site go live. I’m really happy that the Code for America project bucks that trend.

Communication for America

Mandy has written a great article about making remote teams work. It’s an oft-neglected aspect of working on a product when you’ve got people distributed geographically.

But remote communication isn’t just something that’s important for startups and product companies—it’s equally important for agencies when it comes to client communication.

At Clearleft, we occasionally work with clients right here in Brighton, but that’s the exception. More often than not, the clients are based in London, or somewhere else in the UK. In the case of Code for America, they’re based in San Francisco—that’s eight or nine timezones away (depending on the time of year).

As it turned out, it wasn’t a problem at all. In fact, it worked out nicely. At the end of every day, we had a quick conference call, with two or three people at our end, and two or three people at their end. For us, it was the end of the day: 5:30pm. For them, the day was just starting: 9:30am.

We’d go through what we had been doing during that day, ask any questions that had cropped up over the course of the day, and let them know if there was anything we needed from them. If there was anything we needed from them, they had the whole day to put it together while we went home. The next morning (from our perspective), it would be waiting in our in/drop-boxes.

Meanwhile, from the perspective of Code for America, they were coming into the office every morning and starting the day with a look over our work, as though we had beavering away throughout the night.

Now, it would be easy for me to extrapolate from this that this way of working is great and everyone should do it. But actually, the whole timezone difference was a red herring. The real reason why the communication worked so well throughout the project was because of the people involved.

Right from the start, it was clear that because of time and budget constraints that we’d have to move fast. We wouldn’t have the luxury of debating everything in detail and getting every decision signed off. Instead we had a sort of “rough consensus and running code” approach that worked really well. It worked because everyone understood that was what was happening—if just one person was expecting a more formalised structure, I’m sure it wouldn’t have gone quite so smoothly.

So we provided materials in whatever level of fidelity made sense for the idea under discussion. Sometimes that was a quick sketch. Sometimes it was a fairly high-fidelity mockup. Sometimes it was a module of markup and CSS. Whatever it took.

Most of all, there was a great feeling of trust on both sides of the equation. It was clear right from the start that the people at Code for America were super-smart and weren’t going to make any outlandish or unreasonable requests of Clearleft. Instead they gave us just the right amount of guidance and constraints, while trusting us to make good decisions.

At one point, Jon was almost complaining about not getting pushback on his designs. A nice complaint to have.

Because of the daily transatlantic “stand up” via teleconference, there was a great feeling of inevitability to the project as it came together from idea to execution. Inevitability doesn’t sound like a very sexy attribute of a web project, but it’s far preferable to the kind of project that involves milestones of “big reveals”—the Mad Men approach to project management.

Oh, and we made sure that we kept those transatlantic calls nice and short. They never lasted longer than 10 or 15 minutes. We wanted to avoid the many pitfalls of conference calls.

Pattern sharing

Mike has written about the Code for America alpha website that we collaborated on:

We chose to work with ClearLeft because they develop a pattern portfolio (a pattern/style library) which would allow us to scale our work to our Brigades. This unique approach has aligned perfectly with our work style and decentralized organizational structure.

Thankfully, I think the approach of delivering a pattern portfolio (instead of just pages) isn’t so unique these days. Mind you, it still seems to be more common with in-house teams than agencies. The Mailchimp pattern library is a classic example.

But agencies like Paravel are—like Clearleft—delivering systems, not pages. Dave wrote about providing responsive deliverables:

Responsive deliverables should look a lot like fully-functioning Twitter Bootstrap-style systems custom tailored for your clients’ needs.

I think that’s a good way of looking at it: a Bootstrap for every project.

Here’s the front-end style guide for Code for America.

Usually these front-end deliverables will be password-protected on the Clearleft extranet for the client’s eyes only, but Code for America are all about openness, so they’re more than willing to let us share it with the world. That makes me very happy. I remember encouraging the guys at Starbucks to publish their front-end style guide and I’ve written about this spirit of sharing before:

These style guides and pattern libraries aren’t being published in an attempt to provide ready-made solutions—every project should have its own distinct pattern library. Instead, these pattern libraries are being published in a spirit of openness and sharing …a way of saying “Hey, this is what worked for us in these particular circumstances.”

If you’re poking around the Code for America style guide, you’ll notice that it borrows some ideas from the pattern primer idea I published a while back. But in this iteration, the markup is available via a toggle—a nice variation. There’s also a patchwork page that provides a nice glance-able uninterrupted view of the same patterns.

Every project is a learning experience and each front-end style guide gives us ideas about how to do the next one better. In fact, Mark is busy working on better internal tools for creating these kinds of deliverables—something we’ll definitely be sharing. In the meantime, I’ll be encouraging other clients to be as open as Code for America have been in allowing us to share these deliverables.

For more on the usefulness of front-end style guides, be sure to read Paul’s article on style guides for the web, Anna’s classic 24 Ways article, and of course, Anna’s pocket guide from Five Simple Steps.

Coding for America

Back when I was wandering around America in August, I mentioned that I met up with Mike Migurski in San Francisco:

I played truant from UX Week this morning to meet up with Mike for a coffee and a chat at Cafe Vega. We were turfed out when the bearded, baseball-capped, Draplinesque barista announced he had to shut the doors because he needed to “run out for some milk.” So we went around the corner to the Code For America office.

It wasn’t just a social visit. Mike wanted to chat about the possibility of working with Clearleft. The Code for America site was being overhauled. The new site needed to communicate directly with volunteers, rather than simply being a description of what Code for America does. But the site also needed to be able to change and adapt as the organisation’s activities expanded. So what they needed was not a set of page designs; they needed a system of modular components that could be assembled in a variety of ways.

This was music to my ears. This sort of systems-thinking is exactly the kind of work that Clearleft likes to get its teeth into. I showed Mike some of the previous work we had done in creating pattern libraries, and it became pretty clear that this was just what they were looking for.

When I got back to Brighton, Clearleft assembled as small squad to work on the project. Jon would handle the visual design, with the branding work of Dojo4 as a guide. For the front-end coding, we brought in some outside help. Seeing as the main deliverable for this project was going to be a front-end style guide, who better to put that together than the person who literally wrote the book on front-end style guides: Anna.

I’ll go into more detail about the technical side of things on the Clearleft blog (and we’ll publish the pattern library), but for now, let me just say that the project was a lot of fun, mostly because the people we were working with at Code for America—Mike, Dana, and Cyd—were so ridiculously nice and easy-going.

Anna and Jon would start the day by playing the unofficial project theme song and then get down to working side-by-side. By the end of the day here in Brighton, everyone was just getting started in San Francisco. So the daily “stand up” conference call took place at 5:30pm our time; 9:30am their time. The meetings rarely lasted longer than 10 or 15 minutes, but the constant communication throughout the project was invaluable. And the time difference actually worked out quite nicely: we’d tell them what we had been working on during our day, and if we needed anything from them; then they could put that together during their day so it was magically waiting for us by the next morning.

It’ll be a while yet before the new site rolls out, but in the meantime they’ve put together an alpha site—with a suitably “under construction” vibe—so that anyone can help out with the code and content by making contributions to the github repo.

August in America, day twenty-one

I played truant from UX Week this morning to meet up with Mike for a coffee and a chat at Cafe Vega. We were turfed out when the bearded, baseball-capped, Draplinesque barista announced he had to shut the doors because he needed to “run out for some milk.” So we went around the corner to the Code For America office. The place had a layout similar to what we’ve got planned for the new Clearleft building so I immediately starting documenting it with pictures (although it probably looked like I was just trying to sneakily take pictures of Tim O’Reilly).

Office space Office space

After catching up with Mike, I rendezvoused with Jessica back at the hotel and we headed out for lunch at Mel’s diner. The espresso milk shakes there are a must-have on any San Francisco trip I make.

Espresso shakes

Then it was a race against time to try to get to the Mission Bay Conference Center to catch Sophia’s talk at UX Week. She ran the gist of the talk by me yesterday and it sounded great. Alas, I missed the first half of it, but what I caught was reaffirming much of what I was hammering home in my workshops yesterday.

UX Week wrapped up with the inimitable Ze Frank. As I said to Peter afterwards, he’s always reliable but never predictable.

Having said my goodbyes and my thanks to the lovely UX Week people, I met up with Jessica again for a feast of sushi at Hana Zen, right by the hotel. That’s three nights in a row that we’ve had really good asian cuisine downtown: Thai, Chinese, and Japanese.

We finished the evening in good company at the home of young Master Ben, observing the ritual of games night, sipping beers, and resisting the temptation of the cheese.

Tomorrow we depart for Chicago. Farewell, San Francisco; lovely to see you again, as always.