Skip to content

Instantly share code, notes, and snippets.

@tsl-lindsay
Forked from kissane/styleguide.md
Created April 30, 2018 15:23
  • Star 3 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
Embed
What would you like to do?

Style Book

We're currently using the Chicago Manual of Style. It's imperfect, but it's better than the alternatives, so far.

Style Basics & Deviations From the Stylebook

  • We don't wrap article titles within text in quotes, but we do link to them on first usage
  • We don't italicize the names of publications in article text
  • We don't cap "The" in publication titles in article text, but we do in Organization entries
  • Commas and periods go inside closing quotation marks

Semantic Markup + Typography

  • We mostly use unordered lists, which get marked up as such in the HTML; we only use ordered (numbered) lists when the order of the items matters
  • We use strong and em to denote emphasis; for visual differentiation that does not have semantic value, we use classes in CSS -- or, barring that, we can use b and i elements, lightly.
  • We don't use all caps for emphasis
  • We don’t use spaces around dashes.
  • It’s best to wrap all inline code examples in code tags, and code blocks in code and pre tags.
  • We use p tags inside blockquote elements

We should always use

  • Figure captions (for all images—photos, data viz, screencaps)
  • Descriptive alt attributes on images
  • Image credits for everything but screenshots, which should just get the name of the site screenshotted

Capitalization

  • Title case (Chicago rules) in the titles of our articles and the article titles mentioned within text
  • Sentence case for subtitles
  • Title case for headers within articles
  • Sentence case for figure captions (no terminal punctuation needed)

Authors vs. People

Only the people who wrote words in the articles we post get added as Authors. Everyone credited on a project gets added as a Person, with a few exceptions—if someone mentioned in an article is doing straight reporting and no data work/code/design, I don't add him or her as a Person, but I do link to a public profile on the news org page if one exists.

Authors vs. People in the Learning Section

  • Authors are always added as people
  • People and organizations are added if a project of theirs is discussed in depth, not if they are only namechecked

Learning Section Rules

  • Subhead and summary are the same
  • The author name in the summary gets wrapped in STRONG tags, but not in the subhead

Word list

  • internet
  • JavaScript
  • jQuery
  • Ruby
  • URL, URI
  • web, website
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment