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:

PMT style guide

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

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.
Every link to an email address must be an “awesome mailto link”.
- ✓ Currently this is checked automatically in our build scripts (ADD LINK HERE)