Content Guidelines - bradbice.com

House rules for writing and editing content on bradbice.com — blog posts, ratings reviews, work case studies, the contact form, and every label the templates render. Adapted from a general-purpose web content style guide, then trimmed to what this site actually has (no phone numbers, no physical address, no tooltips) and re-grounded in this site’s real copy instead of generic placeholder examples.

This is a reference to write against and revise, not a lint rule enforced at build time. When a rule and the site’s existing voice disagree, match the existing voice and update this doc.

This file is the single source. The same text also renders live on the site, under Design System → Content Guidelines, next to the tokens and patterns it governs.

Headings

One clear H1 per page — the page title.
Heading levels in order. Don’t skip a level just to get smaller text; that’s what a CSS class is for.
Write headings that describe the content that follows, not a label for it.
Keep headings concise.
Sentence case (Design tokens, not Design Tokens), unless a proper noun forces otherwise.
No trailing periods.
Don’t repeat the page title as the first heading inside the page.

Preferred: Top 10 scoring Avoid: Scoring information

Paragraphs and lists

Keep paragraphs short — one idea each.
Break up long sections with descriptive subheadings rather than one wall of text.
Lead with the most important information; don’t warm up before saying the useful thing.
Turn a sentence straining to hold several parallel items into a list instead.
Bulleted lists when order doesn’t matter; numbered lists when it does, when the content is a sequence of steps, or when an item needs to be referenced by number later.
Introduce a list with a complete sentence when the list needs context.
Keep list items grammatically parallel, sentence case, and consistently punctuated — periods for complete sentences, no periods for short fragments, but pick one per list and stick to it.
Avoid a list with only one item, and avoid nesting lists more than one level deep.

Buttons and other actions

Buttons trigger an action in place; links navigate somewhere. Load more on the ratings lists is a button (it renders more of the current page); See the entire list is a link.

Button and control labels:

Start with a verb when practical.
Describe the action, concisely.
Sentence case.
Skip filler words — Click, Tap, Please.

Preferred: Load more, Sort by, Clear search Avoid: Submit, Click here, Proceed

A generic label like Continue is fine only when the action is already obvious from context — a lone button under a single form isn’t ambiguous.

Capitalization

Sentence case for everything — headings, buttons, navigation, labels.

Preferred: Search titles…, Clear search, Design tokens

Reserve title case for proper names (Rotten Tomatoes, The Dark Knight) or an established brand convention. Don’t capitalize an ordinary word just because it names a UI element.

Punctuation

Periods — use them at the end of complete sentences, in body copy, and in instructional text written as sentences. Generally skip them in headings, button labels, navigation labels, short form labels, and brief standalone status text where a period adds nothing (No movies match your filter. is long enough to earn one; Load more isn’t).

Colons — introduce a list or explanation only when the text before the colon is itself a complete sentence.

Exclamation points — sparingly. Don’t use one to make a routine action sound exciting.

Ampersands — write and in prose. Use & only in an official name, when space is genuinely tight, or when an established convention calls for it.

Slashes — avoid as a stand-in for a word when the relationship could be unclear. Prefer and, or, or (when both apply) and/or written out, over a bare slash.

Quotation marks — for direct quotes and titles, not to put “air quotes” around ordinary interface terminology. Bold an interface label instead.

Bold and italics — bold sparingly, to help scanning: interface labels inside instructions, important terms, short phrases someone needs to find fast. Don’t bold a whole paragraph. Italics even more sparingly, and never as the sole carrier of important information. Never underline for emphasis — readers expect underlined text to be a link.

Em dashes and en dashes — en dash for a range (10–20, 2025–2026). Em dash sparingly, for an interruption or aside. In short UI copy a comma, period, or parentheses is usually easier to scan than a dash.

Parentheses — for brief secondary information only. If it’s important enough to need attention, it belongs in the main sentence, not tucked in parens.

Ellipsis — the real ellipsis character …, not three typed periods .... The ratings search placeholder already does this: Search titles….

Numbers

Numerals in interface content — they scan faster than spelled-out numbers (3 files, not three files).
Commas at 1,000 and above (25,000).
No decimal places that don’t carry information (25%, not 25.00%; 4.5 hours, not 4.50 hours).
Percentages: the % symbol with no space before it, joined to the numeral — this is already how every rating badge on the site renders (88%).

Dates and times

General content: July 29, 2026. Avoid a numeric-only date like 07/29/26 when readers could be in different locales.
Tight space: Jul 29, 2026.
No ordinal suffixes — July 29, not July 29th.
Times in a consistent format throughout: 9:00 AM, 2:30 PM. Drop :00 only if that’s already the site’s convention, and stay consistent once you do.
Ranges use an en dash (July 29–31, 9:00 AM–12:00 PM); switch to to when a dash would be less clear than the words.

Email addresses

Lowercase unless capitalization is meaningful. Make the address itself clickable rather than writing Email us here — see the contact page, which links straight to a mailto: rather than routing through filler text.

File names and file types

Recognizable file names over version-litter.

Preferred: accessibility-report.pdf Avoid: final-report-v2-FINAL-new.pdf

Uppercase the file type abbreviation in prose (PDF, CSV, JPG, PNG, SVG). When a link downloads something, name the type and size if it’s useful: Download the accessibility report (PDF, 2.4 MB).

Abbreviations and acronyms

Spell out an unfamiliar abbreviation on first use, then use the short form: Rotten Tomatoes (RT) → RT afterward within the same page. Don’t spell out an abbreviation that’s more familiar than its expansion (URL, PDF, HTML), and don’t invent an abbreviation just to save characters.

Contractions

Use standard contractions where they make the copy read more like a person talking — this is already the site’s voice (I'll get back to you as soon as I can., We couldn't send your message). Avoid an unusual contraction that would slow a reader down.

Navigation labels and breadcrumbs

Navigation labels should be short, use familiar terms, name the destination clearly, follow a consistent grammatical pattern, and skip promotional language. The primary nav is already exactly this: Home, Blog, Work, Library, Contact — nouns for destinations. Use a verb only when the item is itself an action (Sign in, Contact us).

Breadcrumbs (Home > Library > Ratings > Movies) start from the broadest useful parent, end at the current page, and reuse the same labels as the nav and page titles — never a second, slightly different name for the same place. Breadcrumbs are a wayfinding aid, not the only route anywhere.

Page titles

Clearly identify the page, uniquely within the site.
Lead with the most important words.
Match or closely echo the page’s H1.
Don’t pad it with the brand name more than once.

<title> format: Page name - Site name — matching the <title> block already in layouts/baseof.html.

Introductions

Not every page needs one. Add an intro only when it gives the reader context they need before the content itself, and keep it short — don’t just restate the heading in sentence form.

Instructions

Order steps the way a reader will actually perform them. Numbered lists for a multi-step procedure, each step starting with the action, naming the actual control label (bold it) rather than describing it by color or position.

Preferred: Select **Load more**. Avoid: Select the button at the bottom of the list.

Interface labels

Refer to a control exactly as it’s labeled in the UI — if the button says Load more, don’t call it “the load more link” or “the pagination button” in surrounding copy. Bold an interface label when it appears inside prose or instructions (Select **Sort by**, then choose **Ranking (high to low)**.).

Error messages

Explain, in order: what happened, why (if known and useful), and what to do next. The contact form already does this per field rather than with a single generic banner:

Preferred: Enter your email address — it's the only way I have to reply. Avoid: Error: invalid field.

Never blame the reader, and avoid a vague message (Something went wrong., Invalid input.) unless there’s genuinely nothing more specific to say.

Confirmation and status messages

Confirm an action succeeded whenever the result isn’t otherwise obvious, and name the thing that was affected if more than one thing could have been:

Preferred: Thanks — your message has been sent. I'll get back to you as soon as I can. Avoid: Success!

Empty states and placeholder text

An empty state explains what belongs there and, if useful, what to do about it — the ratings lists already do this: No movies match your filter.

Placeholder text (Search titles…) shows an example or the expected format — it is never the only place a required instruction lives, because it disappears the moment someone starts typing. A persistent label carries anything essential.

Forms

Every input gets a real, visible label — never placeholder text standing in for one. Put helper text near the field before the reader needs it, and put a validation message right next to the affected field, the way bb-field__error sits directly under each contact-form input rather than in a summary at the top.

Mark required or optional fields with one consistent convention across a given form. If most fields are required, flag the few optional ones (Phone number (optional)); if most are optional, flag the required ones instead. Never rely on a bare * with no legend explaining what it means.

Tables

Use a table for genuinely tabular data — like the criteria breakdown on /library/ratings/breakdown/ — not as a layout trick. Clear column headings, row headings where they help, consistent alignment, units in the header rather than repeated in every cell, no long paragraphs stuffed into a cell. Check how a wide table behaves on a narrow screen before publishing content that depends on it.

Images, alt text, and captions

The image rules that matter most are already enforced by layouts/_partials/image.html at build time — every image needs alt text or an explicit decorative flag, and the build fails without one. This section is the writing guidance behind that enforcement:

Use an image because it communicates something text alone doesn’t, not to fill space.
Write alt text from the image’s purpose in context, not a generic description. Don’t start it with Image of, Photo of, or Graphic of unless the medium itself is the point.
Don’t duplicate text that’s already right next to the image.
Captions add information beyond what’s visible, in sentence case with normal punctuation — a caption that just repeats the image is redundant.
If a screenshot carries meaningful text, that information also needs to exist as real text nearby, not only inside the image.

Alerts and status notices

Match the alert style to severity and purpose (info, success, warning, error) — this is what bb-form-status--success / bb-form-status--error already do on the contact form. Give an alert a short descriptive heading when the message is more than one short sentence, and don’t reach for warning or error styling just to grab attention for something that isn’t actually a problem.

Search results

Each result needs enough context to tell it apart from a similar one nearby — title, a short excerpt or description, and whatever distinguishes it (category, date, year). Highlighting a matched term can help scanning; it shouldn’t come at the cost of readability.

Truncation

Avoid truncating something a reader needs in full to make a decision (a movie title, a score). If truncation is unavoidable, keep the most distinguishing part, provide a way to see the full value (a title attribute, a link to the detail page), and never truncate an identifier unpredictably. Use the real ellipsis character …, not three typed periods.

Content width and line length

For long-form reading, avoid an extremely wide text column — roughly 50–80 characters per line is the target prose and blog-single image contexts in image.html are already sized against. A line much wider than that makes it harder for the eye to find the start of the next one.

Repeated content

Don’t duplicate the same explanation across multiple pages without a reason. Where practical, keep one authoritative source and link to it — the way the ratings methodology pages (howmovies.html, howtv.html, howgames.html) each state their own criteria once rather than repeating a shared block. If duplication is genuinely unavoidable, know which copy is authoritative and keep the others in sync with it.

Content maintenance

For content likely to go stale — methodology pages, this document — it helps to know who owns it and roughly how often it should be revisited. Update or remove content once it’s no longer accurate rather than leaving it to drift; if a public page is removed and something else on the site covers the same ground, redirect to it.

Pre-publish checklist

Before publishing a page or template change, check:

One clear H1; heading levels are logical and describe their sections.
Paragraphs are short; lists are consistently structured and punctuated.
Links describe their destination; buttons describe their action.
Capitalization is consistent (sentence case, with intentional exceptions).
Dates, times, and numbers follow the conventions above.
Copy matches the actual interface label it refers to.
Every form field has a visible label; every error explains how to recover.
Every meaningful image has real alt text; nothing essential lives only in an image, a tooltip, a placeholder, or a color.
Content is readable at a narrow (mobile) viewport.
Links and references are current.