Example vs guide: what's the difference?

[brendanfalkowski]

Curious what the difference between examples and guides is?

I think it's hard to separate visual style guides, code style, brand guides, copywriting guides, and pattern libraries in practice. For me, there's more overlap than separation (on the web). I tend to just call everything "patterns" and mush them together so it's central.

[maban]

Yeah, it is a little vague. What I wanted to differentiate were styles guide for markup, like Harry Roberts's CSS Guidelines, which focus on how the code is written, and examples of style guides that focus on the website interface. Putting them together felt wrong, but I totally get your point. Maybe I just haven't chosen the right names.

Either way, I should add descriptions to each category to explain what they do.

[brendanfalkowski]

I was looking for a README in guides to see what's meant to be there. Maybe Code Guides and UI Guides? I'd think visual/pattern/brand/copywriting can roll into UI quite well, and code is a kind of different concern.

[maban]

I've just pushed some descriptions to the site and I'd be interested to know what you think.

I want to keep code and copywriting (things like Mailchimp's Voice and Tone and Google's Markup guidelines) separate from the examples (like Starbuck's style guide and Mailchimp's pattern library), because the main thing I'm focusing on is these examples – the pattern libraries and ui.

I think "guides" is probably the wrong word.

[maban]

I've added a readme to the guides folder, thanks for mentioning that it was missing. https://github.com/maban/styleguides/blob/gh-pages/_resourceguide/README.md

[bradfrost]

I have a blog post on exactly this topic coming out soon :)

[maban]

Oh good! I talked about it a bit in my book after my editor said the terms needed to be defined properly (pattern library, ui library, front-end style guide…) because they're confusing, and I felt like a fraud because I don't really know the difference. Everyone calls them different things (myself included), even though some are very similar.

I try to use style guide as the overarching term, front-end style guide when I want to make it clear that I'm not talking about something like a branding style guide, and then pattern library when it's specifically the UI elements. I should draw a venn diagram or something…

I just feel like there's a difference between something that shows UI patterns along with the code for that pattern, and something that explains how to write that code in a way that's easy to maintain, or write content that's in the correct tone of voice for the brand.

And then there are things like Mozilla's style guide or BBC GEL that is really more of a branding style guide and doesn't contain code samples or real UI elements (just pictures of them), but I still want to include it because it's about the web.

Sorry @brendanfalkowski, I feel like I've completely derailed your point.

[brendanfalkowski]

@maban No problem, need to work out what terms mean to have a taxonomy. I often say code standards, style guide, and pattern library. A lot of the examples cross the lines. Maybe it would be good to have a plain "Examples" section and then tag each with the terms that are relevant?

[bjankord]

The term "style guide" has gained new meanings and has become more ambiguous in my opinion, similar to the term, "mobile".

These days a style guide could be something like or Mark Otto's Code Guide which documents coding conventions or something like Dan Eden's style guide which demonstrate the visual styles of the various elements on his site, Dan also has a style guide for his writing which is a whole other type of style guide. A List Apart also has two "style guides" one based around writing and one based around visual patterns.

I'm all for adding clarity to what these terms are. I like the term living style guide or pattern library for things that showcase UI elements/code examples for them. ¯\_(ツ)_/¯

[bradfrost]

Yep, again I have a blog post coming up explaining the difference. But
basically you've hit the general categories: branding, voice, writing, UI,
code.

---

Brad Frost
http://bradfrostweb.com
http://twitter.com/brad_frost

On Mon, Nov 17, 2014 at 11:16 AM, Brett Jankord [email protected]
wrote:

The term "style guide" has gained new meanings and has become more
ambiguous in my opinion, similar to the term, "mobile".

These days a style guide could be something like or Mark Otto's Code Guide
http://codeguide.co/ which documents coding conventions or something
like Dan Eden's style guide http://daneden.me/styleguide/ which
demonstrate the visual styles of the various elements on his site, Dan also
has a style guide for his writing http://daneden.me/styleguide/writing/
which is a whole other type of style guide. A List Apart also has two
"style guides" one based around writing
http://alistapart.com/about/style-guide and one based around visual
patterns http://patterns.alistapart.com/.

I'm all for adding clarity to what these terms are. I like the term living
style guide or pattern library for things that showcase UI elements/code
examples for them. ¯_(ツ)_/¯

—
Reply to this email directly or view it on GitHub
#8 (comment).

[bjankord]

@bradfrost I like that distinction. Looking forward to the blog post!

[susanjrobertson]

Holy cow, this discussion is so perfect for me right now, trying to define all this for a talk!

[bradfrost]

Alright yinz, thanks to this little project I thought it would be time to finally publish that post describing the different flavors of style guides. Here's the post, which maybe we can use for the tagging stuff described in #27.

[susanjrobertson]

I am thinking we can close this, since we have the tagging issue? Unless anyone else feels the need to keep it open.

[bradfrost]

Yep, closing now! Hey guys, this is fun right?