Style guides (a.k.a. pattern libraries, templates)

Notes for style guide discussion for SRCCON 2014.

What is a style guide?

This is my own definition.

A style guide creates standards and best practices for a system or set of decisions that are otherwise subjective.

To note, "style" does not mean that the decisions are visual, it means that the decision that is made is subjective and based on opinion or style.

There are two main questions to think about when defining what a style guide is. The style of what system or set of decisions? And, how are standards and best practices transferred or communicated?

Wikipedia article about style guides

The style of what?

There are many different possibilities of what it is that is being styled.

• digital interfaces (web)
• print design/layout
• code
• copy
• tone
• visualizations
• interactives
• project management

Medium of the guide

How these best practices and standards are communicated can vary as well.

• narrative
• code
• specifications
• generative

Examples

This is not an exhaustive list.

News

News interface examples:

• MinnPost styles: CSS and JS framework for data/interactive pieces.
• Dallas Morning News graphics stylebook: Narrative with explicit values on how to make graphics, includes charts and maps; preumably this is for print and web. Also includes a bit about workflow of how graphics are made as well as maps of the building and where different departments are.
• Chicago Tribune style guide: A CSS and JS framework, altered from Bootstrap for the Newsapps team's pieces.
• Knight lab style guide (Blueline): Web interface style guide.
• WNYC style guide: (experimental) Web interface style guide.
• KPCC Style Guide: Looks to be a web interface style guide, but not actually public anywhere.
• BBC Global Experience Language (GEL): A set of interface and copy guidelines for all digital mediums.

News copy examples:

• Associated Press Stylebook: Copy style guide (reusable and for sale).
• New York Times Manual of Style and Usage: Copy style guide (reusable and for sale).
• The Wall Street Journal Guide to Business Style and Usage: Copy style guide as well as glossary/reference for business terms.
• BBC News style guide: Copy and grammar guide.
  • An older BBC style guide: Copy and tone style guide with a heavy hand of the why for style decisions.
• Economist style guide: Copy and tone style guide.
• Guardian style guide: Glossary style copy guide.
• Telegraph style book: Grammar and copy style guide by topic and glossary.

News code examples:

• NYT Objective-C style guide: Code style guide.

News code project templates:

• Tarbell: Python based templating system for publishing web sites.
• NPR's app templates: Python based template for making NPR news apps.
• MinnPost templates: Yeoman based system for generating MinnPost projects.

Other news examples:

• Propublica's nerds guides: A set of narrative best practices for project philosophy, application components, coding, FB/Twitter HTML tagging, and data processing.
• NPR best practices: A set of best practice documents for project workflow, versioning, and coding for the NPR Visuals team. Tied closely to their app-template.

Non-news

Non-news interface examples:

• Article about Eventbrite's style guide: Looks like a CSS and JS framework.
• Google's HTML and CSS style guide: Instructions on how to write CSS and HTML code.
• Starbuck's general web style guide: CSS and JS framework for (probably) general web assets. Does not seem to be downloadable or much info about it.
• Yelp style guide: CSS and JS style framework for whole site.
  • About
• Github CSS style guide: CSS framework for Github itself.
  • Also includes a mobile interface style guide.
• A List Apart style guide: CSS/JS web interface guide.
• Code for America style guide for web properties: CSS/JS web interface guide.
• MailChimp style guide: CSS/JS web interface guide.
• Editorially style guide: CSS/JS web interface guide.
• Apple's Mac App style guide: Desktop application interface design guide.
• Mapbox style guide: Web interface style guide.
• Salesforce style guide: Web interface design guide.
• Lonely Planet style guide: Web interface design guide.
• Reusable prototyping libraries
  • Twitter's Bootstrap: A CSS/JS web interface guide inspired by Twitter.
  • Barebones: A CSS web interface style guide for a minimal design.

Non-news code examples:

• AirBnB JS style guide: Coding style guides for JS. MinnPost has adopted these.
• Also has a Ruby style guide
• Github style guide: Includes code style guides for CSS, HTML, JS, and Ruby.
• Django Python style guide: Based from PEP8, a more general Python style guide. SMACSS: CSS coding style guide.

Non-news design examples:

• Sunlight Labs Data Visualization guide: CSS-ish guide to data visualization such as charts and maps.
  • What looks to be a CSS/JS implementation of this.
• Best Buy brand identity guide: A set of design guidelines for brand idenitiy management.
• Mozilla style guide: Design and brand style guide for Mozilla and its affiliates.
• Adobe brand guidelines: Specifications and philosophy for design and brand management.
• Government of Alberta, Canada corporate identity: Specifications and philosophy for design and brand management.
• Channel 4 style guide: Specifications and philosophy for design and brand management.
• MailChimp branding: Brand resources and guide.

Non-news copy examples:

• Mailchimp tone and voice: Tone and voice guide.
• Wikipedia style manual: How to write articles.
• ISO standard for "presentation of contributions to periodicals and other serials": ...
• EU style guide: Guide for all written materials from the EU; in 23 languages.
• MLA Style Manual and Guide to Scholarly Publishing: Copy style guide for research and academic works.
• The Elements of Style: General American English copy style guide.
• The Yahoo! Style Guide: General style guide for copy on the web.

Other non-news examples:

• Gov.uk service design manual: Guides and instructions on how to design a service.

References

Helpful links:

• A List Apart "Creating Style Guides"
• A List Apart "Getting Started with Pattern Libraries"
• Clearleft Pattern Portfolios
• Style guide generators
• List of various style guides
• List of brand guides
• FindGuideline.es: Search for brand assets from different organizations.
• Github search for "style" for only orgs listed in CAR-Code.

Discussion

Introduction

• Assign note taker.
• Gatekeeper. If you speak more than twice, you should really think about speaking again.
• Who I am and the like.
• Our recent style guide.
• Goals and outline:
  1. Better define a style guide
  2. What are the benefits and weaknesses
  3. How can we make style guides
  4. Can we make a general style guide
• (depending on how many people in room) Introduce each other
  • Name
  • Org
  • Favorite thing to read on the internet, besides your own org.

Feel for the room:

Question	Answer
How many people have a style guide at their organization for any purpose?	_
How many people have written code? Any amount, including HTML/CSS?	_
How many people have worked on a style guide of any sort?	_

Examples

Let's get the creative juices flowing and look at some examples.

• AP Stylebook
  • Copy and grammar style guide example
  • Standard for American journalism.
  • Not open.
• BBC news style guide
  • Copy and grammar style guide example that is free and public.
  • Cross between dictionary and style guidelines.
• Voice and Tone (MailChimp)
  • Tone example.
  • Not sure why this is a separate site when content is pretty specific to MailChimp.
  • Talks about user feelings and reasoning for responses.
  • Uses examples.
• The Dallas Morning News Graphics Stylebook
  • Example of print-ish design guide.
  • Focuses on graphics, charts, maps, etc.
  • Exact specifications for design and layout of graphics.
  • Even has map of the building to help person get oriented.
• Chicago Tribunes NewsApps style guide
  • Web interface example.
  • Based/forked from Bootstrap.
  • Stylings for near all HTML elements.
  • Reusable components.
  • Code-based.
• Bootstrap
  • Web interface example.
  • Meant for general re-use.
• NYT Objective-C Style Guide
  • Code style guide example.
• NPR Visuals' Best Practices
  • Technical project management guide.
  • Specifics about project structure, versioning, and coding techniques.
  • Ties to their template.
• Tarbell
  • Application/templating system for publishing lightweight web apps.
  • Makes a lot of decisions for you.

Groups (maybe)

Depending on number of people, break out into groups of about 7.

• Number off (if lots of people), or just arbitrarily split the room.
• Assign note taker.
• Assign report(back)er.

Discussion points

For each question, groups should discuss then report back to whole group.

1. What are the types of things that have style?
   • What could have a style guide?
   • Try to aim broad, like "code". But if you get in the details, that's alright too.
2. What are the benefits and weaknesses of style guides?
   • How would you sell the idea to your org?
   • What are the perceived roadblocks of creating a style guide?
3. How would you go about creating a style guide? im
   • Pick a type of style guide. For interface, for code, for copy.
   • What are the parts you need?
   • Who do you need for it?
   • How do you keep it up to date?
   • How do ensure others are using it?
   • What tools or techniques would you use (or have you used)?
   • How do you get buy in?

• Can or should we make style guides to use across multiple newsrooms?
  • For instance, the AP Stylebook.
  • Or the ProPublica Nerd's Guide

Discussion notes

Types of things to style?

• Devops best practices. Example: TwelveSteps
• Code (syntax)
• Internal communication
  • Tools to use
  • Tone
  • Ensure email has a subject
• External communication, tone
• General computer use
  • File sharing
  • Password management
• Code of Conduct
• Design
  • Typography
  • Colors
• Photography
  • Processing
  • Resizing
• Advertising
• Interaction patterns
• Web interface
• Copy, grammar

Pros and Cons

• Pros
  • Helps with onboarding new employees or contributors to project.
  • Less debate about stylistic things
  • Generally saves time
  • Provides an essential, referencable source
  • Forces decision making
  • Can require thinking about accessibility or other things that may be often overlooked.
  • Helps maintain control and scope on projects
  • Makes things that don't follow require and show importance. Shining breakthroughs.
  • Don't have to start from scratch
  • Suppresses whims of superiors
  • Requires specific understanding of why there is a need to break or go outside the style guide.
  • Offers a good amount flexibility. "guide" not "rules".
  • Offers ownerhip
    • Will be used by team that creates it
  • Solidifies branding and identity
  • My original list
    • Saves time building.
    • Makes communication smoother.
    • Provides consistency.
    • Easier to maintain whatever the style guide is for.
    • Can provide for an early testbed.
    • (CSS) Ensures most minimal amount of CSS is written.
• Cons
  • Requires time, commitment, and execution
  • Requires maintenance
  • Requires buy-in and use
  • Might have to defend (often) against haters.
  • Could provide a false send of security
    • Ex. just because an app passes Apple's guidelines, doesn't make it useful or important.
  • Can stifle innovation or creativity
  • Requires adjustment period to use
  • Balancing comprehesiveness and flexibility
  • Can become stale
  • Not always shared across organization
    • Ex. Print department may have their own style guide, while the web department does too
  • How to reconcile web and print style guides
  • Overall investment
  • Can become too authoritative, or "gospel-like"
  • Misuse of the style guide
  • Not having ownership can mean not using
    • If team uses old team's style guide
  • Can be a significant barrier to entry, specifically to contributing to a (open source) project.
  • Can be very negative if style guide goes against larger, universal styles
  • My original list
    • Takes time to create.
    • Takes time to maintain.
    • May limit creativity.
    • Requires expertise.

Thoughts on making style guides for SRCCON/journalism community.

• A guide on which (open source) tools are the best and why.
• Tough to reconcile between standards and best practices.
• "PEP8 for journalism"?
  • Is there specific coding styles that are needed for journalism.
• Best ways to write a README geared towards the journalist audience.
• Best ways to release open source software for journalists.
• Best ways to evaulate tools
• Philosphies and values could be shared across the community.
• Reconcile principle versus styles
• What is practival for everyone as opposed to specific to a brand or identity
• The AP Stylebook is somehwat unique/driven-by that their content is distrbuted across many organizations
• Making audio expercial for everyone