Grammar & Mechanics
The mechanical rules JMF writing follows: punctuation, lists, contractions, abbreviations, acronyms, voice, and emphasis. A lookup, not a lecture.
Punctuation
Small marks, consistently applied, never decorative. Where two marks could work, pick the one that adds less visual weight.
| Mark | Rule | Example |
|---|---|---|
| Period | End of full sentences. Skip on fragments in buttons, labels, and short list items. | “Vendor saved.” / Button: “Save changes” |
| Em dash (—) | Use sparingly for parenthetical thoughts in prose. Do not use in UI strings. | “The vendor — once approved — appears in search.” |
| En dash (–) | Use for numeric and date ranges only. | Jan 5–Jan 9, 2026 |
| Hyphen (-) | Use for compound modifiers and hyphenated phrases. | First-class support |
| Curly quotes (“ ”) | Always curly in prose. Straight quotes only in code. | “We’re shipping.” |
| Curly apostrophe (’) | Curly in prose. Possessives standard. | Vendor’s compliance |
| Comma | Use the Oxford comma. | Vendors, suppliers, and partners |
| Colon | Introduces a list or related clause. Capitalize what follows only if it is a full sentence. | “Choose one: vendor, supplier, or partner.” |
| Semicolon | Use sparingly. Joins two related independent clauses. Almost never in UI. | “We saved the vendor; the change is live.” |
| Exclamation point | Almost never. Reserved for genuine celebration. Never in errors. | “Welcome to The Hub” (no exclamation) |
| Ellipsis (…) | Use the single character. Indicate truncation or async pause. | “Loading…” |
| Parentheses | Asides only. If the aside is essential, rewrite without them. | “Vendor (status pending) saved.” |
| Slash (/) | Avoid. Spell out “and” or “or” when possible. | “Vendor or supplier” not “Vendor/supplier” |
| Ampersand (&) | UI shorthand only (page titles, navigation). Never in body prose. | “Voice & Tone” (page title) / “vendors and suppliers” (prose) |
Lists
Every list needs three things in place: the right shape, parallel structure across items, and consistent punctuation.
- Use a numbered list when order matters. Steps in a process, ranked priorities.
- Use a bulleted list when order does not matter. Options, features, optional reading.
- Keep items parallel. Every item starts with the same part of speech: verb, noun, or adjective.
- Capitalize the first word of each item. Sentence case.
- Period at the end if the item is a complete sentence. No period for fragments. Stay consistent within a single list.
Parallel structure
- Add vendor
- Compliance tracking
- You can also export reports
- Add vendors
- Track compliance
- Export reports
On the left, the three items mix a verb phrase, a noun phrase, and a full sentence. On the right, every item starts with an imperative verb. The list becomes scannable.
Contractions
Contractions sound human. Use them where the tone is conversational. Spell them out where the tone is formal or where the contraction could be misread.
| Where | Rule | Example |
|---|---|---|
| Product UI and conversational copy | Use contractions. | “We couldn’t save your changes.” |
| Help text, tooltips, notifications | Use contractions. | “You’ll get a confirmation email.” |
| Policy, compliance, legal copy | Spell out. | “You will receive a confirmation email.” |
| Documents quoting policy verbatim | Match the source. | Preserve the original phrasing. |
Watch-outs
- “It’s” (it is) vs. “its” (possessive). Mix-ups are common; reviewers should flag.
- “You’re” vs. “your.” Same.
- Avoid stacked contractions like “we’d’ve” or “shouldn’t’ve” in any context.
Pronouns and voice
Two rules, almost no exceptions.
| Element | Rule | Example |
|---|---|---|
| Pronoun for the reader | “You.” Singular, second person. Never “the user.” | “Add a vendor to your watchlist.” |
| Pronoun for the company | “JM Family” or “the company.” Avoid “we” speaking for the enterprise. | “JM Family vendors must submit insurance.” |
| Voice | Active voice in instructions. Passive only when the actor is genuinely unknown. | “Submit your request.” not “Requests should be submitted.” |
| Tense | Present for state. Imperative for instructions. | “Your request is pending.” / “Click Save.” |
Abbreviations
Spell out in titles, first sentences, and policy text. Abbreviate in data-dense UI and informal copy when the abbreviation is more common than the expansion.
| Abbreviation | Use | Avoid |
|---|---|---|
| e.g. | Inline examples in body prose. | Headings, titles, button labels. |
| i.e. | Clarifying restatement in body prose. | UI strings; rephrase instead. |
| etc. | End of a non-exhaustive list. | When the list IS the answer. |
| vs. | Compact comparison. | Formal copy. |
| approx. | Data-dense UI. | Body prose; say “about.” |
| min., max. | Data-dense UI labels. | Body prose; spell out. |
| am, pm | Times. Lowercase, no periods. | “AM/PM” capitalized. |
| US, UK | Region labels. No periods. | “U.S.A.,” “U.K.” |
Acronyms
Spell out an acronym the first time it appears on a page, with the acronym in parentheses, then use the acronym from there. Skip the expansion only for acronyms that are more recognized than the spelled-out form for the JMF audience.
Worked example: “Personal Time Off (PTO) requests over five days require manager approval. Submit PTO at least two weeks in advance.”
Canonical JMF acronyms (skip the expansion)
| Acronym | Expansion (for reference) |
|---|---|
| PTO | Personal Time Off |
| HRNow | HR Now |
| ITNow | IT Now |
| SSO | Single Sign-On |
| MFA | Multi-Factor Authentication |
| VPN | Virtual Private Network |
| KB | Knowledge Base |
| ETA | Estimated Time of Arrival |
Always spell out on first use
- SETF (Strategic Enterprise Task Force)
- RGM (Regional General Manager)
- Any acronym with fewer than three published uses across the JMF intranet
Quotation marks and emphasis
Curly quotes always. Emphasis is rare and load-bearing. If everything is bold, nothing is.
| Mark | Use | Avoid |
|---|---|---|
| Curly quotes (“ ”) | Quoted speech, titles of short works, scare quotes (sparingly). | Straight quotes outside code. |
| Italics | Product names on first reference, titles of long works, technical terms on first reference. | Italics for emphasis as a default; bold serves emphasis better. |
| Bold | UI elements being referenced in instructions, emphasis on a single key word. | Bolding whole sentences or every important word. |
| Underline | Never in prose. Underline means “link” everywhere else on the web. | Underlining for emphasis or titles. |
| ALL CAPS | Acronyms only. Section labels and headings use sentence case with type weight. | Caps for emphasis (reads as shouting). |