Skip to main content

​
Why media needs its own guide

Images can make a question much better or much worse. The right image can clarify anatomy, show a clinical finding, or make a matching prompt instantly understandable. The wrong image can reveal the answer too early, distract from the core concept, or create accessibility problems. That is why media in LearnTerms is structured, not casual.

​
What attachments are currently for

The current attachment system is built for images attached to questions. This is useful for content such as:
  • anatomy diagrams
  • pathology photos
  • tables captured as images
  • labeled figures
  • charts students need to interpret

​
Current upload rules

Question media currently follows a few important rules:
  • images only
  • 8MB maximum size
  • one question can have multiple attachments
  • each attachment has ordering metadata
If a file does not behave like an image or is too large, LearnTerms rejects it.

​
The fields you should care about

Every attachment can include:
  • image file
  • alt text
  • optional caption
  • display order
  • optional Show on solution behavior
These are not filler fields. They affect how the student experiences the question.

​
Alt text is not optional in spirit

The system requires alt text because attachments need to remain understandable even when the image is not doing all the work by itself. Good alt text should:
  • identify what the image is
  • capture the key educational detail
  • stay concrete
Bad alt text usually does one of two things:
  • says almost nothing, like “image”
  • says far too much and turns into a mini explanation
Aim for useful context, not a hidden lecture.

​
When to use captions

Use captions when the student benefits from a small amount of framing that does not belong in the stem itself. Good caption use cases:
  • naming the view or orientation of a figure
  • noting what structure is highlighted
  • giving brief source context
Do not use captions to smuggle in the answer.

​
Use Show on solution intentionally

This is one of the most important media controls in LearnTerms. When Show on solution is enabled, the image is treated as review-only or answer-reveal content. Depending on the surface, LearnTerms can blur or hold it back until solution view. Use this when:
  • the image would make the answer obvious immediately
  • the image is better as an explanation than as a prompt
  • you want the student to reason first and verify second
Leave it off when:
  • the image is required to answer the question fairly
  • the student needs the visual from the start

​
What a strong media-assisted question looks like

A strong media-assisted question has a clear relationship between:
  • the stem
  • the image
  • the answer
  • the rationale
The image should do real work. It should not just decorate the card.

​
What weak media usually looks like

Weak attachment usage often falls into one of these patterns:
  • the image is redundant with the stem
  • the image gives away the answer before the student thinks
  • the image is too small, messy, or poorly cropped
  • the alt text is useless
  • the caption explains the answer instead of supporting the question
If you notice one of these, fix it before publishing.

​
Good contributor habits

  • Add media only when it improves understanding.
  • Crop aggressively so the student sees the relevant detail.
  • Write alt text as if it actually matters, because it does.
  • Use Show on solution whenever the image would collapse the question too early.
  • Review the question in study flow, not just in the editor.