Course contentsShow
← Software Engineering
Lesson 832 of 1,93326. API Contracts and DocumentationFree lesson

Writing Clear Descriptions

Crafting concise, unambiguous descriptions for resources, fields, and behaviors that users understand.

Writing Clear Descriptions

What you'll learn: How to write API documentation descriptions that your users can understand without confusion or guesswork.

Clear descriptions are the bridge between your API's technical implementation and the humans using it. After you've structured your reference documentation, the actual words you write in each description make the difference between a developer confidently calling your API and one who's frustrated, confused, or using it incorrectly.

The Core Principle

Write descriptions as if you're explaining to a colleague who knows programming but has never seen your API before. Be specific, concrete, and unambiguous. Avoid jargon unless it's standard in your domain, and when you must use technical terms, explain them.

Think of descriptions like cooking recipe instructions: "Add salt" is vague. "Add 1 teaspoon of salt" is better. "Add 1 teaspoon of kosher salt to the boiling water" is crystal clear.

What Makes a Description Clear

For resources: Explain what the resource represents in the real world and its purpose.
Unclear: "User object"
Clear: "Represents a registered user account with authentication credentials and profile information"

For fields: State the data type, what it contains, and any constraints.
Unclear: "status field"
Clear: "status: string - Current order state. One of: 'pending', 'processing', 'shipped', 'delivered', 'cancelled'"

For behaviors: Describe what happens, including side effects.
Unclear: "Creates a payment"
Clear: "Creates a payment transaction and immediately charges the customer's default payment method. Returns an error if insufficient funds are available"

Common Pitfalls to Avoid

  • Don't assume users know your internal terminology
  • Avoid circular definitions ("The ID is the identifier")
  • Don't leave out critical details like units, formats, or constraints
  • Never write "self-explanatory" — if it were, you wouldn't need the description

Key Takeaway: Clear API descriptions eliminate ambiguity by being specific, complete, and written from the user's perspective, not the implementer's.