Skip to main content
Code blocks don’t work in isolation. Readers either need context to understand what they’re looking at, or they need to be trusted to read the code themselves. The right balance of explanation depends on what type of page you’re writing and who’s reading it.

​
How does the content type affect explanation?

Reference pages are looked up, not read top-to-bottom. Someone reading an API reference page already knows what they want. They are after the parameters, the types, and a quick example. Long prose explanations slow them down.
Reference page example
## Create user

Creates a new user and returns the user object.

**POST** `/users`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Full name |
| `email` | string | Yes | Email address |

```json Response
{
  "id": "usr_01J...",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "created_at": "2025-01-01T00:00:00Z"
}
```
No prose about what a user is, why you’d create one, or what happens after. The reference page trusts the reader knows what they want to do, they just need the details. How-to guides explain the steps, not the concepts. Readers need the path forward. Brief prose before code blocks identifying what’s about to happen is helpful. Paragraphs explaining why the API was designed this way are not. Tutorials explain reasoning alongside steps. Beginners need to understand not just what to do but why, so they can troubleshoot when things go wrong. Code blocks in tutorials often warrant a brief explanation of what the code does and what to expect from it.

​
Inline comments versus prose

When only part of a code block needs explanation, inline comments are often more clear than a paragraph of prose after the code block. However, consider if people will be copying and pasting the code block, in which case a comment might be more confusing than helpful. 
client = mintlify.Client(
    api_key=os.environ["API_KEY"],  # Never hardcode your key
    timeout=30  # Increase if you're uploading large files
)
Use inline comments for:
  • Non-obvious choices (“why 30 seconds for a timeout?”)
  • Things that are commonly misconfigured (“should I use api_key or API_KEY?”)
  • Variables the reader will need to replace (“replace YOUR_API_KEY with your actual API key”)
Avoid inline comments for things that are obvious from the code, or for adding step numbers like # Step 1: Initialize the client. If the comment restates what the code says, you probably don’t need it.

​
Explain before, not after

For how-to guides and tutorials, one sentence before the code block identifies what’s about to happen and gives readers context for what they’re reading.
Explain-then-show pattern
Create a client instance with your API key. You'll reuse this client throughout your application.

```python
client = mintlify.Client(api_key=os.environ["API_KEY"])
```
The sentence creates context then the code demonstrates. The reader who already knows Python sees the sentence and can predict the code. The reader who’s less comfortable reads the sentence and then has a frame for the code. Don’t explain code after it appears. People need context before the code so they’re primed to understand it. If readers encounter code they don’t understand, they might stop or leave the page. They don’t keep reading hoping an explanation appears later.

​
What counts as obvious depends on the reader

Content for beginners needs more explanation than content for experienced users. A step that’s obvious to someone who’s written API integrations before might not be obvious to someone setting up their first integration. Before deciding how much to explain, consider your audience for the specific page where the code block appears. If you’ve defined your readers as developers with API experience, trust that experience. If you’re writing for people who are new to using your product and APIs, explain the parts that experienced users take for granted.
Next up: Tabs — When your content varies by environment, audience, or stack, tabs let readers see only what applies to them.