---
title: Contributing to Documentation
sidebar:
  label: "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](https://github.com/strands-agents/sdk-python).

## 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](https://astro.build/) and the [Starlight](https://starlight.astro.build/) theme.

```bash
# 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

<Tabs>
<Tab label="Python">

```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?")
```
</Tab>
<Tab label="TypeScript">

```typescript
--8<-- "contribute/contributing/documentation.ts:basic_agent"
```
</Tab>
</Tabs>

