Style Guides with Susan Robertson

Susan Hi Anna!

Susan Good. How are you today?

Susan Sure. Currently I'm a freelance front-end developer and I focus mostly actually on CSS and mark-up. I actually don't do a lot of JavaScript, so I focus a lot on CSS architecture, large-scale CSS, style guides, CSS audits and I like to think of myself as a design implementer, which is something that Jonathan Snook coined on his blog, so I work a lot with designers and help them get things the way they're supposed to be.

Susan Pretty much, yes, and usually I'm brought in to just help get things going and it kind of varies from project to project but I usually work closest with the designer on any given team.

Susan Yes; I was the front-end developer at Editorially which I guess I should say, since it's been gone over almost a year now. For those who don't know, it was a collaborative writing software online.

Susan Me too, believe me! And when I was brought in there, they were getting ready to head into public beta and Ethan Marcotte who built the application was going out of day to day and I was brought in to replace him, which was a little frightening, actually! And so I worked for them from probably the last six and a half months of the lifespan of the company before we shut down.

Susan Yeah. When I came in there, I was really interested in building a style guide and so I had agitated pretty hard in the interviews about asking the co-founders what they thought of it and if they thought it was a good idea. They were all fairly receptive, so my first few weeks there I started building out a guide based on the existing application. I had gotten pretty used to guides in my workflow at previous jobs, so I kind of don't like working without one for any long-term project.

Susan Yeah, it was. My previous job I'd done a lot of building out, it was a development consultancy, so we'd done a lot of waterfall type of building out, so we would get designs and then build from there, so building on an existing application that's actually changing as you're building was definitely a different scenario for me, but I really enjoyed it. It was the way I got to learn all the different CSS that was used in the application and could see it all, every single button that had been styled, even if they weren't all being used, and it was a way to familiarise myself with everything going on within the code. And I also took it as an opportunity to do some re-factor as well.

Susan Well, the first part, the styles were in Sass but Ethan isn't a huge user of all the features of Sass so they were basically in Sass because it was a Rails app and the Rails pipeline could concatenate the files together, so even more breaking up of files to get things like, all the buttons were alone in a file and the navigation alone in a file and that kind of thing and then I implemented variables which we weren't using up until that point for colours and I was able to find CSS that wasn't being used anywhere and double and triple-check that and have a colleague check for me as well before I deleted it out. And that was pretty helpful because I think when you're iterating quickly on an application, that happens a lot; you abandon a module for something totally different, so you want to start over and so I was able to clean a lot of that up as well and get a system in place for prefixing as well for vendor prefixes, so it worked pretty well.

Susan Yeah.

Susan I tried. That got a little hairy in some of the situations, just because a lot of things were tied together and I didn't really know where to break them, but a colleague of mine that I worked with there, he and I liked to talked about screenfuls of code; we didn't want more than one to two screenfuls, so you were scrolling a lot in a code file, so my goal was usually to narrow it down just so that you wouldn't have as much to scroll through in any given file, but sometimes that's hard.

Susan And I think it's easier for someone to step into, because they can just find… here's the buttons, here's the icons, here's the colour box, here's the media box, or whatever it is, however you do it. You name the file after what the thing is that's in there and so it's easier, because with Sass it's become a little harder to find things. The inspector says some odd line and you're like, I have no idea where that is! It's usually a concatenated file, so I think that's made it easier to step into projects as well.

Susan Right, exactly, exactly.

Susan For Editorially it's pretty old-school. It was Rails App, so we had basically an HTML file or ERBs as they're known in the Rails world, sitting in our Admin area and I hooked up the production style sheets to that page and I hooked up a style guide only CSS to that page just in case I would need it, and then I actually just hand-wrote everything at the beginning, so I just started throwing everything in; the buttons and the paragraphs and things like that, so I could see them. And as I iterated, I then used… Ethan actually suggested after he took a look at some early iterations, using Filament Group's X-Ray HTML, so that we could spit out actually what the code actually was underneath each module.

Susan Yeah, it uses just a little bit of JavaScript and you can use Lea Verou's Prism for colour coding if you want. We used it, but since we were already using it in the application to colour code any code bits you put in a document, it was kind of Editorially grey colours; it didn't colour code in the same way that out of the box it does. But it was really nice to have and that's where I felt like the style guide took another giant step forward, because you could look at it and just see everything in one place.

Susan We worked pretty quickly and we were a very small team, and we worked very agilely, and we didn't have a staging server or anything, so it was local and production, so we would do all our new features in local and typically we just did the features and the changes and then if it required mark-up changes to something or to a module, it was on me basically to go back and change it in the style guide and update it. I was the one who cared the most and since we were trying to move pretty quickly and we were in beta pretty much the entire lifespan of the app, it's just we moved from private to public, it was just easier that way to go forward and I would just double back. I think eventually I would have wanted an automation of some kind, but we were small enough that I didn't feel like it was worth the work at that point.

Susan My very, very first glimpse of anything relating to a style guide, and I don't know that it even used the word style guide was, I was sitting at An Event Apart in Seattle several years ago now, and Aaron Walter from MailChimp was on stage and he was talking about how they'd implemented object-oriented CSS and done a lot of clean-up under the hood of MailChimp and at the same time they'd come out with a style guide that was just on their intranet, and he had an image of it. He actually still has an image of it; it's this huge, long image.

Susan Yeah, on Flickr. And that was my first ever… wow, that's a thing? And kind of thinking about that, the job I was at I couldn't really figure out how I would get something like that, but it definitely piqued my interest and I started to look out for anything remotely like that as things were coming out.

Susan Well, I've been trying to timeline that and I'm pretty sure that that image from his talk was pre your 24 ways article and pre Starbucks' being released, so I think the year he did that talk was really the first, it would be for a lot of people, if they went to An Event Apart that year, or heard that particular talk, their first glimpse, because nothing else was really out there, nobody was talking about them very much.

Susan Right; exactly.

Susan Yeah.

Susan Yeah, totally agree.

Susan Yeah, I think it was too. I think it sat in their intranet for quite a while before anything came out publicly. So that image was kind of the one thing you could look at!

Susan Well, it never went public during the lifespan of that application; it went public as the application was in its final months and I was writing the article for A List Apart and I was using basically how I made that style guide to write the article and so I asked the co-founders, is there any way that could come out of the application and be public at this time, and so they agreed to put it out on GitHub so it's out there, but my big caveat that I tell everyone is, to get it out as a standalone little thing, I had to actually just view source and save the HTML and then save all the style sheets… so it is on GitHub but it is pretty dang gnarly to look at that code.

I think it would have taken a while for that to become public if the application had kept going because Jason would have wanted to design it and make it look better, but I've found it really helpful to have it out there looking kind of crappy because I think our standards for what a style guide needs to look like are based on all the ones that are public and all the ones that are public have designers behind them who wouldn't let them be public unless they were beautiful! And I think an internal team document doesn't need to look that good to be helpful and the majority of the style guides I have made in my time look bad. They don't look like Yelp or Starbucks or any of the others that are publicly available; Rizzo; they look pretty bad! But they were just internal team documents so nobody else had to see them but us!

Susan If I were sharing I'd probably want it to look good too, so I totally understand the motivation! But it doesn't help the normal average person working on a team of people understand that you don't have to go to those lengths to make a style guide that's going to help you and your team; it's great if you want to do that but you don't have to do that.

Susan Yeah, I have.

Susan Yep!

Susan I just did a lot of tool research because I had a client who wanted something that would generate so I needed to come up with what I would use, and the one I ended up using was Styledown. It's fairly lightweight and pretty easy to get going; it's a Node based tool and one command line spits out your style guide, once you have a config file you start putting comments in your style sheets and then you can run a command and it spits out HTML and he also has set up a bunch of CSS and JavaScript that's sitting on a CDN that you can access, so it can look pretty good pretty quickly right out of the gate, which is nice.

I also looked heavily at Nico's Living Style Guide; he's in Berlin and he's getting ready I think for his 2.0 or something; he's tweeted at me a little bit about making changes, so I kind of have a run-down on the A List Apart blog of all the ones I looked at. A lot of the Node ones are nice because they're fairly lightweight, so they're pretty easy to get up and running, but it depends on your application; if you're in Ruby, there's some great options that run right off of RubyGems, and so could be easy to use something like that. I've been looking at the pattern labs; I've never used Brad's but I've looked into it and I've also looked at your Jekyll version of a pattern lab.

Susan Yeah! Which I'm intrigued by; I use Jekyll for my sites so I've considered doing my own little mini style guide for my site out of that but there's a lot of tools out there. And the biggest thing I've found is, everybody wants you to use a tool but most tools aren't completely automated so you still have some maintenance that has to happen manually, even if you use a tool.

Susan Yeah. My recent project I was really lucky, the designer was willing to run the one line in his command line, and so that was nice, but that's not always the ideal situation for people. You have to think about all that as well, for sure.

Susan Yeah. Rizzo is kind of the Holy Grail to a lot of people and I think it's great; I love Rizzo and I love what Ian's written about it and how open he's been about it and how open he's been about it but the big thing with Rizzo is you have to have access to full stack and you also have to be able to… you probably want to tailor it to your needs; your needs might not be exactly the same as Lonely Planet's, so I think Rizzo would take a lot of up-front work, even if you were an in-house team, but then once it's running, it could be really great. But I get a lot of questions about Rizzo and I love Rizzo but like you, I work with clients so I don't have full stack access and that's not necessarily going to be a solution for them.

Susan The first time I ever did one for a client was the project for FiftyThree, where I did this type style guide and they came to me looking for a refactor and a cleanup of the type across their site and I was like, well if we're going to do this, why don't we just tack on a style guide; wouldn't that make it easy? So they were pretty receptive to that and additionally it went out publically because they're FiftyThree and they design, so they gave me a beautiful design, basically, to get it out the door and make it look nice, which was great.

Last summer I worked with a startup where I did a style guide for them and that one was mostly me saying, I think this is a good idea; I don't know how long you guys are going to have me around and I should document this front-end, and so we did a rough and ready style guide so that the back-end folks would have something to reference if they needed it, because I was only with them part-time too, so I wasn't always around and there were time-change issues because they were on the East Coast. So I just did it, kind of thing! I said, I think you need this and it's not really going to take me that long so I'm just going to do this.

But the first time I ever had a client say, I want a style guide as part of what we're doing was the project I just wrapped a couple of weeks ago, so he came to me; he's a designer, he was working with a client, he was bringing me in to help architect and build out the front end and we were passing off static pages but he really wanted a style guide for reference for them as they moved forward with the application and even he wasn't around because he was on contact, so he was going to have an end date, so that was the first time it was like, we want this and we had to figure out how we can do this easily, so that's why I did a whole bunch of research and came out using Styledown, but that usually isn't the case. A lot of clients aren't quite sure what the benefit is so they see it as extra work.

Susan But then once you build them something, they realise the benefit! So it's kind of like this chicken and egg of trying to help them understand the benefit. I did a really fast five day project last week and she came to me with all these designs and it was great and I was like, well why don't we do a style guide because I could have just done all the components for her, and then out of that whipped up templates for her to start in on and she wasn't down with it, so I just did the flat file templates, so a lot of folks don't see benefit all the time, which is too bad.

Susan This has become the hottest topic I've found in the last six months and I tweeted asking people basically, how do you maintain, last November and I tweeted about it and I ended up spending all day on Twitter talking about maintenance with people who either are like, "We don't know how to maintain: tell us." or people who were like "This is what we do."

It was a little nutty and it was interesting to see all the different types of people that were interested in it. And out of that came a conversation that I actually got to do a Google Hangout and talk with Livia Labate, she was at Marriott until the end of last year, now she's a Knight Fellow working with NPR, visual stuff.

Susan She has, yes, she's on the Responsive Web Design podcast. The two things about maintenance are; Lonely Planet comes up a lot as we've discussed for fully automation, and I'm fairly sure that Ian and Lonely Planet are the only fully automated solution I've seen. I really haven't seen another one.

But then on the flip side of that is Marriott who is a huge organisation with tons of digital teams and they actually have a team of four or five people who are paid to maintain their standards and govern.

Susan Yeah! It's really crazy.

Susan And they have an internet standards library basically, and their standards team has issues that are submitted by the digital teams across Marriott; they work through issues in a sprint and then present back to the greater company and then if there are rush needs, they'll work with that team to figure out what needs to be done for that particular project and then they'll work it back into the standards after the fact and their standards are crazy; it's not just… I always use icon fonts because I think it's kind of controversial and everyone has different opinions on how to use them, so if you were to look in Marriott's standards portion of their intranet about how do you use icon fonts, it wouldn't just be like; here's what we do, here's how you use them. It's actually the entire history of how they decided to do what they did and then how you would use them so that anyone coming into the company, instead of re-hashing stuff that they've already gone through, all that historical mileage is documented so that everyone can see why they're doing it the way they're doing it and all the things they've thought about to get there, so the intent of how they use things is really well documented.

And then they have a smaller what we would consider more of a code style guide for front-end developers to use as reference and to quickly be able to get up to date but then they can always click back into the standards from there to read more should they need to.

So it's really amazing what they're doing, but they're paying a lot of people to do it, but they're a huge company and they have managed to rein in and standardise tons of stuff because of that. Governance is pretty hard and maintenance is definitely really hard and I think for small companies a lot of times it comes down to, there's a person on the team who care and they make sure it stays up to date. And who knows what happens when that person leaves the company? But that's usually what I'm hearing from a lot of people is they care and so they maintain.

But even a larger client that I've worked with, one that I worked with last fall on the size of Marriott, they would do a lot of PRs after the fact to clean up the style guide, so they'd get through, get things made and then there would be all these clean-up PRs coming through to update the style guide, because they were using KSS and they had to remember to do all the comments and put the mark-up in the files and stuff. But that was part of their process.

Susan Yeah, but that was part of their process. One of the things I've talked a lot about is the same project I worked on last fall, the end client, I had to run a command-line test suite before I could even do a PR, and it was like a fifteen minute test suite; it was like you hit the button and you walked away because they were wanting to make sure that nothing broke and there were linters involved and it's the right thing to do; it's painful for the individual developer but their code base stayed much cleaner and so I think if you have those kind of standards already in place and you're using a style guide, that part of that workflow, so you hit the command-line test suite, you do your PR and then maybe as a part of the PR, the PR doesn't get signed off until the style guide's updated too. I think you can work these checks and balances in if you want. It's no different than testing in some ways.

Susan Yep.

Susan I think if I were working for… even if I weren't just client working, but I think teams that are working on a new app or a new thing and they're iterating really, really quickly, I don't know that they should do a style guide.

Editorially didn't have a style guide when I came on board and there were a lot of reasons for that and most of them are really good reasons; Jason Santa Maria who was the creative director has an image on Dribbble of all the different menu bars that were inside when you're working on a document; what you'd see at the top, and it's this huge image and it's just like one little menu bar after another of all the different things he designed and thought about when he was working through that, trying to find a design solution and according to Ethan, half of those got built out! So they're moving really fast and they're making changes and they're in private beta and they're trying to figure out what they're doing and I like to say, you're trying to figure out what the thing you're building is; what is it? And I don't think that at that point, a style guide's necessarily helpful for you.

Susan Yeah, and tons of design in code, tons of iteration, tons of changing. And if you had a style guide at that point, you would be constantly having to do maintenance to update it; you would constantly either be, even if you were using a tool, because the mark-up's probably changing, so I don't know that I would say you have to have a style guide at that point. I think once you've settled on a design language and you know where you're at and you feel good about where you're at, I think that's actually the time to start documenting because your app is growing up, if that makes sense?

Susan Your app has gone through its crazy toddlerhood of changing all the time and…

Susan Yeah, exactly, and so once you're to the phase where you're kind of settling and growing up a little bit, then that might be the right time to start implementing a style guide.

Susan Right, yeah, I think that's perfectly OK. I don't have a style guide for my site!

Susan No kidding!

Susan I worry about that actually. Someone's going to ask me about the style guide for my own site because I've referred to Max Quattromani's and that's his personal site and he's got this killer style guide and I'm like, someone's going to ask me; one of these times someone's going to be like, "Where's your style guide?" and I'm going to be like, "Oh, yeah, I haven't done that!" So…

Susan Yeah, it's always your own site that you leave until last I think.

Susan Thank you!

Susan Bye!