Contributing to documentation

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 docs 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.

Setup

!!! warning "Migration in progress" This section will be rewritten as we migrate to a new CMS.

Let's get the docs running locally so you can preview your changes as you work. The docs are built with MkDocs Material.

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

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Start the local development server
mkdocs serve

# Preview at http://localhost:8000

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 docs 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 mkdocs serve 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.

Writing style

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

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

# 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="anthropic.claude-3-sonnet"),
    system_prompt="You are a helpful assistant."
)
agent("What's the weather like?")