Skip to main content
Code needs the right amount of context. Too little leaves beginners guessing; too much slows down experienced readers. The balance depends on the page and its audience.

​
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
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 clearer than a paragraph after the block. Keep them short, because readers who copy the code copy the comments too.
Inline comments
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, confirm 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
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 save the explanation for after the code. If readers hit code they don’t understand, they might stop or leave the page rather than keep reading in hopes of an explanation. After the code, say what should happen when it works, if that isn’t obvious: “The request returns 201 Created and the new user’s ID.” That’s not an explanation of the code. It’s how readers know they can move on.

​
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 and code groups—let readers switch to the version of the content that applies to them.