Skip to content

Instantly share code, notes, and snippets.

@kiostark
Forked from kissane/styleguide.md
Last active December 20, 2015 06:08
Show Gist options
  • Save kiostark/6083254 to your computer and use it in GitHub Desktop.
Save kiostark/6083254 to your computer and use it in GitHub Desktop.

Style Book

We're currently using Chicago, but we can switch to AP if there's a good reason. (Like, say, Chicago annoying our entire readership.)

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 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.

##Specific to Learning Section

  • Authors are also added as people
  • People and organizations are added if a project is discussed in depth, not if they are only namechecked
  • Subhead and Summary are the same

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