sdk-dx

SDK Design and Developer Experience

The best SDK marketing is an SDK that developers can't stop talking about. When your SDK makes developers feel productive and competent, they become your advocates. When it frustrates them, no amount of marketing will save you.

Overview

SDK developer experience (DX) encompasses everything a developer feels when using your library:

• Discovery: How easily can they find and install it?
• Learning: How quickly can they understand how to use it?
• Using: How productive are they day-to-day?
• Debugging: How easily can they fix problems?
• Upgrading: How painlessly can they adopt new versions?

Great SDK DX is a competitive advantage. Developers choose tools that make them feel smart.

Before You Start

Review the developer-audience-context skill to understand:

• What languages and frameworks do your target developers use?
• What IDE/editor setups are most common?
• What's their experience level with your problem domain?
• What competing SDKs have they used? What do they like/dislike?

SDK design decisions should flow from deep understanding of your users.

API Design Principles

Principle 1: Optimize for the Common Case

The most frequent use case should require the least code.

Good Design:

# Common case: send a simple message
client.messages.send("Hello world", to="+1234567890")

# Full control when needed
client.messages.send(
    body="Hello world",
    to="+1234567890",
    from_="+0987654321",
    status_callback="https://...",
    media_urls=["https://..."]
)

Bad Design:

# Every call requires full configuration
message = Message(
    body="Hello world",
    to=PhoneNumber("+1234567890"),
    from_=PhoneNumber(config.get_default_from()),
    options=MessageOptions(
        status_callback=None,
        media_urls=[]
    )
)
client.messages.send(message)

Principle 2: Progressive Disclosure

Start simple, reveal complexity as needed.

// Level 1: Simplest possible usage
const result = await client.analyze("Hello world");

// Level 2: Common options
const result = await client.analyze("Hello world", {
  language: "en",
  features: ["sentiment", "entities"]
});

// Level 3: Full control
const result = await client.analyze("Hello world", {
  language: "en",
  features: ["sentiment", "entities"],
  model: "v2-large",
  timeout: 30000,
  retries: { max: 3, backoff: "exponential" }
});