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.
- ✓ 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)