Skip to content

Instantly share code, notes, and snippets.

@kissane

kissane/styleguide.md

Forked from kiostark/styleguide.md
Last active April 30, 2018 15:23
Show Gist options
  • Star 6 You must be signed in to star a gist
  • Fork 2 You must be signed in to fork a gist
  • Save kissane/6235108 to your computer and use it in GitHub Desktop.
Save kissane/6235108 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
styleguide.md

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