Contributing to Documentation

Good documentation helps developers succeed with Strands. We welcome contributions that make our docs clearer, more complete, or more helpful. Our documentation lives in the site/ directory of the Strands SDK repository.

What we accept

We’re looking for contributions that improve the developer experience. Documentation changes can range from small typo fixes to complete new guides.

| Type | Description | |------|-------------| | Typo fixes | Spelling, grammar, and formatting corrections | | Clarifications | Rewording confusing sections | | New examples | Code samples and tutorials | | New guides | Complete tutorials or concept pages | | Community extensions | Documentation for community-built packages |

Setup

Let’s get the docs running locally so you can preview your changes as you work. The docs are built with Astro and the Starlight theme.

# Clone the repository
git clone https://github.com/strands-agents/sdk-python.git
cd sdk-python/site

# Install dependencies
npm install

# Start the local development server
npm run dev

# Preview at http://localhost:4321

The development server automatically reloads when you save changes, so you can see your edits immediately.

Submission process

The submission process varies based on the size of your change. Small fixes can go straight to PR, while larger changes benefit from discussion first.

1. Fork the repository on GitHub
2. Create a branch with a descriptive name like docs/clarify-tools-usage or docs/fix-typo-agent-loop
3. Make your changes in your favorite editor
4. Preview locally with npm run dev to verify formatting and links work correctly
5. Submit a pull request with a clear description of what you changed and why

For small changes (typos, grammar fixes, minor clarifications), you can skip local preview and go straight to PR. We’ll catch any issues in review.

For larger changes (new guides, significant rewrites), we recommend opening a GitHub Discussion first to align on approach and scope.

Style guidelines

We aim for documentation that teaches, not just describes. A reader finishes understanding the “why” before the “how.” This section covers our voice, writing style, and code example conventions.

Voice and tone

Our documentation uses a collaborative, developer-peer voice. We write as knowledgeable colleagues helping you succeed.

| Principle | Example | Why | |-----------|---------|-----| | Use “you” for the reader | “You create an agent by…” not “An agent is created by…” | Direct and personal | | Use “we” collaboratively | “Let’s install the SDK” not “Install the SDK” | Creates partnership | | Active voice, present tense | “The agent returns a response” not “A response will be returned” | Clear and immediate | | Explain why before how | Start with the problem, then the solution | Builds understanding |

Writing style

Keep prose tight and focused. Readers scan documentation looking for answers.

| Do | Don’t | |----|-------| | Keep sentences under 25 words | Write long, complex sentences with multiple clauses | | Use “to create an agent, call…” | Use “in order to create an agent, you should call…” | | Include code examples | Describe without showing | | Use tables for comparisons | Use long bullet lists for structured data | | Add lead-in sentences before lists | Jump directly into bulleted lists |

Code examples

Code examples are critical—they show developers exactly what to do. Always test your examples before submitting.

• Test all code — every example must actually work
• Include both languages — provide Python and TypeScript when both are supported
• Start simple — show the minimal example first, then add complexity
• Add comments — explain non-obvious parts
• Use realistic names — avoid foo/bar, use descriptive names

Python

# Good: Start simple
from strands import Agent
agent = Agent()
agent("Hello, world!")

# Then show configuration
from strands import Agent
from strands.models import BedrockModel

agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514"),
    system_prompt="You are a helpful assistant."
)
agent("What's the weather like?")

TypeScript

import { Agent, BedrockModel } from '@strands-agents/sdk'

// Good: Start simple
const agent = new Agent()
await agent.invoke('Hello, world!')

// Then show configuration
const configuredAgent = new Agent({
  model: new BedrockModel({ modelId: 'us.anthropic.claude-sonnet-4-20250514' }),
  systemPrompt: 'You are a helpful assistant.',
})
await configuredAgent.invoke("What's the weather like?")