Writing policies and style guide

This applies to medical and non-medical articles published on our websites.

We are very open in the topics we will consider, but the format of our articles must follow strict requirements:

Prose

• 100% original prose (⚠️ writers that break this rule will be immediately removed from our team)
• Each section should link to authoritative sources of additional information
• Each link includes a description
• Read our linking policy (⚠️ writers that break the linking policy may be immediately removed from our team)
• 100% correct spelling and grammar
• Prose should be broken into paragraphs, lists, and callouts and should use bold for important text
• Recommend an image for your article
• Use additional images in the article if it is helpful

This is how we evaluate our writing:

https://static.googleusercontent.com/media/guidelines.raterhub.com/en//searchqualityevaluatorguidelines.pdf

Capitalization, word choice, headings

We require sentence case everywhere. Even in titles and headings. There are limited exceptions to this rule, and each are detailed in this section.

Proper nouns

• Proper nouns, like Dick Tracy, are in title case. You can tell something is a proper noun by seeing its Wikipedia article. Spoiler: personal protective equipment is not a proper noun, but Good Samaritan is.

Buttons

• We follow Apple’s HIG specification for text capitalization in buttons. This requires title-style capitalization, and Apple has a good specification for this.

Heading word choice

• The heading structure (h1/h2/h3) for each page should support the inbound search keywords are targeting for that page. For example:
  • ❌ h1: Free Hands On Skill Testing
  • ✅ h1: Online ACLS certification

Typesetting

Punctuation

• Use n-dash without spacing for ranges. Example: 10am–2pm.
• Phone numbers in the US are formatted like +1 212-555-1212. Or if the audience is absolutely certain to be in the US, you can use 212-555-1212.

Initialisms (e.g. “ACLS”) and abbreviations (e.g. “dept.”)

• For our courses, every initialism must be defined on first use. Use parenthetical offset because these will show when if/when course materials are printed. For example:

  My car is packed so I drive in the HOV (high occupancy vehicle) lane. Driving in the HOV saves money because it can avoid fees on toll roads.

• For our online articles, use your judgement as to whether a parethentical offset is necessary. But every single time, do be sure to use an abbreviation tag. In HTML this is:

  <abbr title="high occupancy vehicle">HOV</abbr>
  

• When spelling out the words of an initialism, still use sentence case. Use “cardiopulmonary resuscitation”, because that is not a proper noun.

HTML / Jekyll code style

• Everything we publish is usually a permalink, so if we move something we intend to redirect from the old page to the new page. Exceptions are made if we see nobody is linking to the old page.

• All pages we publish must have a canonical URL.

  • And this should not have a file extension.
  • And it should truncate any trailing /index.
    • x Check this manually using egrep '/index[.a-z]*"' **/BUILD/**/*.* (this produces false positives) this check is not currently scheduled into our regular reviews
  • And we should only link to our pages at the canonical URL.
    • ✓ Currently this is checked automatically in our build scripts (add link here)

• Every page must have the Jekyll front matter tag “required_reviews” set to “none”, “medical” or “AHA” as appropriate.

• Each page should have one H1 and it should match or very closely match the title of the page
• H2s for a page should be designed so that targeted SEO keywords are put on those pages instead of the H3.
• Every link to an email address must be an “awesome mailto link”.
  • ✓ Currently this is checked automatically in our build scripts (add link here)

Images

• All images must use SVG or WebP lossy format. Keep a copy of the editable or lossless image in our Google Drive.
• Size images at maximum of 800px max side for inline images, 1200px max side for full-width images.

You can use this command to resize and convert to WebP:

# Convert to WebP lossy
# If image is horizontal (or square) and over 800px use "-resize 800 0"
# If image is vertical and over 800px use "-resize 0 800"
# Otherwise, skip the resize part
cwebp -q 80 -m 6 -mt -v -resize 800 0 -o output.webp input.png

Videos

All videos must be encoded in .webm format using VP8 codecs. A copy of the original high-resolution source video should be kept in our Google Drive. Follow these guidelines for video encoding:

Resolution Guidelines

Scale videos using FFmpeg’s scale filter.

• Full-width videos:
  • 1920x1080 (Full HD): For high-quality desktop playback.
  • 1280x720 (HD): For mobile optimization or general web use.
• Inline or small videos:
  • 854x480 (SD): For smaller placements or bandwidth-saving scenarios.
  • 640x360 (Low resolution): For minimal bandwidth consumption.

640px is the default scale value for hero-callout videos. Select a width value from the list above.

 ffmpeg -i input.mov -vf scale=640:-2 -c:v libvpx -q:v 10 output.webm

Conditions for Switching to VP9

• Browser support improves universally across our audience.
• File size reduction without sacrificing quality becomes critical.
• Video transparency is required.

Properly link HTML videos

To properly link the converted video using the HTML video element, use as such:

Adjust video attributes as necessary ```html

```

URLs

Choosing URLs for content we pubish is important to make sure we clearly communicate the page intent, and we have durable URLs that will still be relevant if we make updates to the page.

Use apex domain

• ✅ Good: https://example.com
• ❌ Bad: https://www.example.com

Localization prefix

Our websites are multilingual and multilocale. We organize our site content into folders based on language and locale. These rules below assume that example.com is serving customers in different locales, and the base language (implicit language for pages without a prefix) is English.

• No prefix: /(index.html) page is in English and is relevant to people anywhere on Earth
• No prefix: /some-page page is in English and is relevant to people anywhere on Earth
• Locale prefix: /en-US/california page is in English and is relevant only to people in US country (United States)
• Locale prefix: /fr-CA/quebec page is in French and is relevant only to people in CA (Canada)
• Language prefix: /fr/exemple-page page is in French and is relevant to people anywhere on Earth
  • Even /fr/quiz/exemple-quiz should be under the namespace (because the French quizzes will have a different layout template than the English quizzes)
• Note: you must not use a country prefix without a language, (e.g. /ca)

Assets work a little differently. We allow pages at like /some-page because it is more succinct than /en/some-page and visitors will see the URL. However for assets, we do not expect visitors to see these URLs and we explicitly include the locale in the URL every time.

• Global prefix: /images/global/some-image.webp (and /assets/global/some-asset.xyz, etc.) this image for style only, and is relevant to people in ANY language anywhere on Earth. But the name of the file is in English.
• Language prefix: /images/en/product-algo-cards.webp this image is only relevant to our pages in English.
• Locale prefix: images/en-US/states-map.webp this image is only relevant to our pages in English for visitors in US.

Slugs

A slug is a component of a URL that does not include slashes. For example some-page which is part of /en-US/some-page.

Rules:

1. Don’t use capital letters: ✅ ACLS, ❌ acls
2. Use hyphen to separate words: ✅ acls-algorithms, ❌ acls_algorithms
3. Use words economically, and omit “a”, “an”, “the” (and their translated equivalents): ✅ exemple-page, ❌ exemple-du-page
4. Avoid accent letters: ✅ recertification, ❌ récertification (in French)