Last updated: June 29, 2021

Writing Policy

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:

• 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 will 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

PMT style guide

Words, capitalization, headings

Headings

• Use title case only for a course name, or an article name (i.e. the first H1 on the page).
  • This policy may change later to use sentence case for these situations.
• For all other headings and prose use sentence case.
• Capitalize proper nouns, you can tell something is a proper noun by seeing the corresponding Wikipedia article. Spoiler: personal protective equipment is not a proper noun, but Good Samaratan is.
• For navigation items, use sentence case.

Buttons

• Use verbs in title case. An action-specific title shows that a button is interactive and says what happens when you tap it.

• Use title-case for titles. Capitalize every word except articles, coordinating conjunctions, and prepositions of four or fewer letters.

• Keep titles short. Overly long text can crowd your interface and may get truncated on smaller screens.

• This rule is adopted from Apple’s Human Interface Guidelines and relevant rules for macOS and iOS.

Punctuation

• Use n-dash without spacing for ranges. Example: 10am–2pm.

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.
    • :white_check_mark: 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.

• Every link to an email address must be an “awesome mailto link”.
  • :white_check_mark: Currently this is checked automatically in our build scripts (ADD LINK HERE)