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