📝 Writing Style Guide

Core Writing Philosophy

Write Like a Textbook, Not a Slide Deck

Our goal is to create narrative, flowing prose that reads like a conversation with an expert clinician. We're not creating bullet-point summaries – we're teaching complex concepts through clear explanation and reasoning.

The Problem With Bullet Points

Bullet points are useful for lists, but they create a fragmented reading experience when overused. Consider this example:

Notice how the narrative version:

• Explains why, not just what
• Uses natural transitions between concepts
• Incorporates clinical reasoning organically
• Maintains reader engagement through conversational tone
• Builds a mental model instead of isolated facts

When to Use Bullets

Bullets are appropriate for:

✅ Acceptable Uses:

• True lists – Discrete items without explanation (e.g., the four heart valves)
• Differential diagnoses – Quick reference lists
• Steps in a procedure – Sequential actions
• Quick reference summaries – After detailed explanation has been provided

❌ Avoid Bullets For:

• Explaining mechanisms or pathophysiology
• Clinical reasoning or decision-making processes
• Anything requiring more than 1-2 sentences per point
• Sequential concepts that build on each other

Active Learning Techniques

Use Questions to Engage Critical Thinking

Questions force readers to actively process information rather than passively consume it. Use them strategically throughout your writing.

Types of Questions to Use:

1. Anticipatory Questions – Set up what you're about to explain:

"Why does aortic stenosis cause a crescendo-decrescendo murmur instead of a constant sound?"

2. Socratic Questions – Guide reasoning step-by-step:

"Think about it: if the left ventricle is stiff and non-compliant, what happens when the atrium tries to push blood in during late diastole? That's right – you get an S4."

3. Clinical Reasoning Questions – Promote active recall:

"A patient's murmur gets louder with squatting. Does this suggest HCM or mitral regurgitation? Before you read on, reason it through using what you know about preload and afterload."

4. Self-Check Questions – End sections with application:

"Pause here and ask yourself: Could I explain to a colleague why standing makes HCM louder? If not, re-read the hemodynamics section."

The "Stop and Think" Technique

Occasionally pause the narrative and explicitly ask the reader to engage:

This forces active processing and prevents passive skimming.

Narrative Structure Guidelines

Start With the "Hook"

Open each section by establishing why this matters or what puzzle we're solving. This primes the reader's brain to care about what follows.

Example:

"Mitral valve prolapse is one of the most common valvular abnormalities you'll encounter – up to 2-3% of the population. Yet it's also one of the most misunderstood. Here's why it's so clinically fascinating: it's a dynamic lesion. The murmur actually changes timing depending on the patient's position and volume status. Let's explore why that matters."

Build Conceptual Scaffolding

Introduce foundational concepts before complex ones. Each paragraph should build logically on the previous.

Template:

1. What is it? – Basic definition
2. Why does it happen? – Mechanism
3. What do you hear? – Clinical findings
4. How do you prove it? – Diagnostic reasoning
5. Why does it matter? – Clinical significance

Use Transitions Between Concepts

Avoid abrupt topic changes. Guide the reader from one idea to the next.

Good transitions:

• "Now that you understand the mechanism, let's explore how this sounds clinically..."
• "This brings us to an important question:"
• "Here's where it gets interesting:"
• "Notice the pattern emerging..."
• "Building on what we just learned..."

Formatting & Visual Elements

Headers: Use Hierarchically

H2 – Major topic shifts (e.g., "Mechanism", "Clinical Presentation")
H3 – Subtopics (e.g., "Acute vs Chronic", "Auscultation Technique")
H4 – Minor points within subtopics

Rule: Don't use a header unless it introduces at least 2-3 paragraphs of content. If it's just 1 sentence, integrate it into prose.

Info Boxes: Strategic Use

Use colored boxes to highlight key concepts, but sparingly. Too many boxes create visual clutter.

Info Box (Blue) – Key concepts, synthesis points
Warning Box (Red/Orange) – Critical clinical pearls, red flags, "don't miss" items
Tip Box (Green) – Practical bedside advice, mnemonics, study tips

Frequency guideline: Maximum 2-3 boxes per page. If you're using more, some content should be in regular prose.

Tables: When Comparison Is Key

Tables are excellent for:

• Comparing similar conditions side-by-side
• Showing maneuver responses across multiple murmurs
• Summarizing key differentiating features

But: Always provide context before and after the table. Don't just drop a table without explanation.

Tone & Voice

Be Conversational, Not Casual

Write as if you're explaining to an intelligent colleague over coffee. Use "you" and "we" to create connection.

✅ Good: "You'll notice that the murmur gets softer when the patient squats. Why? Let's think through the hemodynamics."

❌ Too Formal: "It is noted that the intensity of the murmur decreases upon assumption of the squatting position."

❌ Too Casual: "So yeah, squatting makes it quieter, lol."

Confidence Without Arrogance

Be authoritative but humble. Acknowledge when things are complex or uncertain.

Good: "This is a tricky distinction that even experienced clinicians sometimes miss."
Bad: "Obviously, anyone can tell the difference between..."

Avoid Unnecessary Jargon

Use medical terms when appropriate, but explain them the first time. Don't use jargon to sound smart – use it because it's precise.

First use: "The murmur exhibits a crescendo-decrescendo pattern – it gets louder then softer, like a diamond shape on a phonocardiogram."

Subsequent uses: "This crescendo-decrescendo murmur..."

Clinical Examples & Vignettes

Make It Real

Abstract concepts stick better when tied to clinical scenarios. Include realistic patient presentations throughout.

Common Pitfalls to Avoid

❌ Don't Do This:

• Wall of bullets – Converting every sentence to a bullet point
• Header overload – Using H3 or H4 for every single sentence
• Passive voice – "It is heard..." → "You'll hear..."
• Redundancy – Saying the same thing in a box and in prose
• Orphan headers – Headers followed immediately by another header
• Facts without context – Stating what without explaining why

Quick Reference Checklist

Before finalizing any page, ask yourself:

• ☐ Did I prioritize narrative prose over bullet points?
• ☐ Did I use questions to engage active learning?
• ☐ Did I explain the "why" not just the "what"?
• ☐ Are my transitions smooth between concepts?
• ☐ Did I include at least one clinical scenario or example?
• ☐ Is my tone conversational but professional?
• ☐ Did I use boxes sparingly (≤3 per page)?
• ☐ Are my headers hierarchically organized?
• ☐ Could a student reason through this, not just memorize it?

Examples: Before & After

Example 1: Aortic Regurgitation

Summary

Our writing style isn't about being flowery or verbose – it's about creating understanding through narrative. We're building mental models, not memorization lists.

Remember:

• Prose > Bullets
• Why > What
• Questions > Statements
• Reasoning > Memorization

When in doubt, ask yourself: "Am I teaching someone to think like a clinician, or just giving them facts to memorize?" Aim for the former.

Interactive Elements: Making Learning Active

Static content teaches. Interactive content transforms. Every page should include opportunities for active recall, self-testing, and immediate feedback. This section outlines our complete interactive element system.

Core Pedagogical Principles

Our interactive elements are grounded in learning science:

• Retrieval Practice – Testing strengthens memory more than re-reading
• Immediate Feedback – Corrects misconceptions before they consolidate
• Spaced Repetition – Reviewing content at increasing intervals improves retention
• Varied Formats – Different question types engage different cognitive pathways
• Progressive Disclosure – Revealing complexity gradually prevents overload

Question Types (Pedagogical Function)

Different questions serve different learning goals. Use the right type for your purpose:

1. Anticipatory Questions

Purpose: Prime the learner's brain before presenting new information

Format: Blue box with thought bubble emoji 💭

Example: "Before we explain the mechanism, ask yourself: Why would a stiff ventricle create a sound during atrial contraction?"

Implementation: Click-to-reveal answer (see UI Patterns below)

2. Socratic Questions

Purpose: Guide step-by-step reasoning through a complex concept

Format: Green box with brain emoji 🧠

Example: "Let's reason through this. If preload increases, what happens to ventricular volume? And if volume increases, what happens to flow across a stenotic valve?"

Implementation: Multi-step walkthrough (progressive reveal)

3. Clinical Reasoning Questions

Purpose: Apply knowledge to realistic scenarios

Format: Orange box with stethoscope emoji 🩺

Example: "A 65-year-old with a systolic murmur performs Valsalva and the murmur gets louder. What's your top differential?"

Implementation: MCQ with detailed explanations

4. Self-Check Questions

Purpose: End-of-section comprehension check

Format: Purple box with checkmark emoji ✓

Example: "Can you now explain why squatting decreases the HCM murmur without looking back?"

Implementation: Click-to-reveal or text entry

5. Integration Questions

Purpose: Synthesize information across multiple sections

Format: Red box with puzzle emoji 🧩

Example: "Compare the response to squatting in HCM, MVP, and MR. What's the underlying hemodynamic principle?"

Implementation: Complex MCQ or matching exercise

UI/UX Patterns: Implementation Guide

These are the mechanics of how users interact with questions. Each pattern includes complete implementation examples with refined, academic styling.

Pattern 1: Click-to-Reveal

Best for: Low-stakes reflection, anticipatory questions, quick self-checks

Design Principles:

• Subtle cream background (#FBF8F3) - no bright colors
• Thin border in course brown (#CD853F) - refined, not blocky
• Typography-first: Use font weight/size for hierarchy, not color
• Generous padding and whitespace
• Smooth transitions (0.3s ease)

Full Working Example (Interactive):