What you’ll learn
- How to choose between components that look similar but signal different things to readers
- When plain prose or a list is better than a component
- How to guide readers through procedures, including ones that branch by platform or role
- How to present code, variations, comparisons, API details, and visuals
- How to point readers to their next step without cluttering the page
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 out 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 users 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 sample code
- 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.
Present content that varies by environment or stack
- Tabs and code groups—Let readers pick their language, platform, or role.
- Conditional content—Change a whole page with views, or show different content to people and agents.
Show a comparison of options
- 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.
Document APIs
- Components for API documentation—Document parameters, responses, nested objects, and examples.
Add visual context
- Images, frames, and diagrams—Choose visuals that explain something prose cannot.
Direct users to related content
- Cards and links for navigation—Match the visual weight of a link to the importance of the destination.
- End-of-page navigation patterns—Help readers decide what to do next.
Use supporting components
- Small components with specific jobs—Decide when tooltips, updates, panels, prompts, file trees, tiles, icons, and colors belong on the page.