Written Style Guide

IA

Anything linked to from the main menu is a “landing page”. A landing page is a collection of sections. A section is a grouping a guides. A guide is an individual piece of content.

A landing page will link to a section detail page, but also a list of the guides in that section.

A section has an index page that gives a high-level summary of the guides and a list of the guides. It will include a video introducing the topic

Capitalization and naming

• Across the site, for hyphenated words, capitalize as if the hyphens weren’t there (e.g., “Multi-Device” and “Peer-to-Peer”).

Website section titles

• Title case capitalization (e.g., “Multi-Device Layouts” not “Multi-device layouts”).
• Avoid verbs in top-level section titles.

Article titles

• Title case capitalization (e.g., “Responsive Web Design Basics” not “Responsive web design basics”).
• Use imperative verbs when possible (e.g., “Set the viewport” not “Setting the viewport”).

Headlines within articles

• Sentence case for headlines in articles: “Use placeholders for images”.
• Use imperative verbs when possible (e.g., “Set the viewport” not “Setting the viewport”).

Linking to external articles

• Related reading to our articles: Add them in.
• Don’t lean on external resources; bring content into your article when necessary (e.g., link to API reference, but not to an explanatory from another developer).

“Mobile” vs. “multi-device” vs “multi-screen” vs “mobile-only” vs “mobile-first”

• Use “multi-device” for consistency except when a different term is needed for precision.

Article length

• One key “concept” per article (e.g., “use the correct input type in your forms”).

Tone of voice

• Active, rather than passive.
• Use present tense, unless referring to the future event (e.g., future bug fix).
• Informal pronouns and abbreviations, when it simplifies text, but don’t over-use.
• Avoid unnecessary adjectives.

Code samples

• Every article should have at least one nontrivial use-case-based example.

Key takeaways / TL;DR

• One section of TL;DRs per article.
• Use the name “TL;DR”, not “Key takeaways”.
• Keep each of them brief.

Media

• All images need to be in 3:5 or 5:3 ratio.
• Images will be compressed for you during the deployment step. You do not need to worry about compressing your own images.