What you’ll learn
- How to choose between components that look similar but signal different things to readers
- When standard prose or a plain list is better than a rich component
- How to handle procedures that branch by platform, role, or user choice
- How to use code blocks, code groups, and inline explanations to match your audience’s needs
Who this is for
Anyone who contributes to documentation on Mintlify and wants to use components more deliberately. It’s especially helpful if you’re new to technical writing or writing for the web.Lessons in this course
Call attention to important information
- Choose the right callout — What each callout type tells readers.
- When callouts stop working — How to recognize and fix callout fatigue.
- Site-wide, page-level, and inline signals — When to use banners, tags, and badges.
Guide readers through a process
- Steps or numbered lists — Choose the right structure for a sequence.
- Describe branching procedures — Help readers follow the path that applies to them.
- When a procedure outgrows a page — Split a long procedure without losing the thread.
- Progressive disclosure with accordions — Keep optional details nearby without hiding the main path.
Share code and variations
- Code block essentials — Make examples easier to understand and use.
- When to explain code and when to just show it — Match the explanation to the reader and page.
- Tabs for platform and audience variation — Show one relevant version without hiding a comparison.
- Code groups for multi-language examples — Let readers choose their language.
- Conditional content — Change an entire page with
<View>.
Compare and describe structured information
- Tables for structured comparisons — Use rows and columns when the content is genuinely tabular.
- Columns and cards for visual comparisons — Give richer options more room.
- Components for API documentation — Document parameters, responses, nested objects, and examples.
Add visual context and navigation
- Images, frames, and diagrams — Choose visuals that explain something prose cannot.
- Cards as navigation — Help readers choose a destination.
- Inline links or cards — when to use each one — Match the visual weight to the importance of the link.
- End-of-page navigation patterns — Help readers decide what to do next.
Use smaller supporting components
- Small components with specific jobs — Decide when tooltips, updates, panels, prompts, tiles, icons, and colors belong on the page.