# MCPTesta Documentation

This directory contains the comprehensive documentation for MCPTesta, built with [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/) following the [Diátaxis](https://diataxis.fr/) documentation framework.

## Documentation Structure

The documentation is organized according to Diátaxis principles, with four distinct types of content serving different user needs:

### 📚 Diátaxis Organization

#### 🎓 Tutorials (Learning-oriented)
*"Can you teach me to...?"*

Step-by-step lessons that take the reader by the hand through a series of steps to complete a project:

- **[Your First Test](/tutorials/first-test/)** - Write and run your first MCPTesta test
- **[Testing Walkthrough](/tutorials/testing-walkthrough/)** - Explore MCPTesta's testing capabilities  
- **[YAML Configuration](/tutorials/yaml-configuration/)** - Master advanced configurations
- **[Parallel Testing](/tutorials/parallel-testing/)** - Optimize test execution performance

#### 🔧 How-to Guides (Problem-oriented)
*"How do I...?"*

Practical guides that show how to solve specific problems:

- **[Test Production Servers](/how-to/test-production-servers/)** - Safe production testing strategies
- **[CI/CD Integration](/how-to/ci-cd-integration/)** - Automate testing in pipelines
- **[Troubleshooting](/how-to/troubleshooting/)** - Diagnose and resolve issues

#### 📖 Reference (Information-oriented)
*"What are the options for...?"*

Complete and accurate descriptions of the machinery:

- **[CLI Reference](/reference/cli/)** - Complete command-line interface documentation
- **[YAML Reference](/reference/yaml/)** - Comprehensive configuration format specification
- **[API Reference](/reference/api/)** - Full Python API documentation

#### 💡 Explanation (Understanding-oriented)
*"Why does this work this way?"*

Discussions that clarify and illuminate how and why:

- **[MCP Protocol Testing](/explanation/mcp-protocol/)** - Understanding MCP protocol testing concepts
- **[Architecture](/explanation/architecture/)** - MCPTesta's design and architectural decisions
- **[Testing Strategies](/explanation/testing-strategies/)** - Methodologies and approaches

## Development

### Prerequisites

- Node.js 18+ 
- npm or yarn

### Local Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

### Content Structure

```
docs/
├── src/
│   ├── content/
│   │   └── docs/
│   │       ├── introduction.md
│   │       ├── installation.md
│   │       ├── tutorials/
│   │       ├── how-to/
│   │       ├── reference/
│   │       ├── explanation/
│   │       └── community/
│   ├── styles/
│   │   └── custom.css
│   └── assets/
├── astro.config.mjs
├── package.json
└── README.md
```

## Writing Guidelines

### Diátaxis Principles

When contributing to the documentation, ensure content follows Diátaxis principles:

**Tutorials:**
- Use "we" language and hands-on approach
- Provide reliable, tested step-by-step instructions
- Focus on learning, not teaching
- Build confidence through visible results
- Minimize explanation

**How-to Guides:**
- Start with the user's problem
- Provide a series of steps to solve it
- Focus on practical usability over completeness
- Handle real-world complexity
- Write from the user's perspective

**Reference:**
- Be neutral and authoritative
- Mirror the product's structure
- Avoid instruction or explanation
- Provide complete, accurate information
- Optimize for consultation

**Explanation:**
- Make connections between concepts
- Provide higher perspective
- Be readable "in the bath"
- Answer "Can you tell me about...?" questions
- Offer informed opinions and context

### Content Guidelines

**Clarity**: Write for developers of all skill levels
**Completeness**: Cover the full scope of each topic
**Currency**: Keep examples and information up to date
**Consistency**: Use consistent terminology and formatting
**Accessibility**: Ensure content is accessible to all users

### Code Examples

**Working Examples**: All code examples should be tested and functional
**Context**: Provide sufficient context for examples to be understood
**Comments**: Include helpful comments in complex examples
**Error Handling**: Show both success and error scenarios

### File Naming

Use kebab-case for all files:
- `testing-walkthrough.md`
- `ci-cd-integration.md`
- `mcp-protocol.md`

## Contributing

### Content Contributions

1. **Identify the content type** using Diátaxis principles
2. **Check existing content** to avoid duplication
3. **Follow the appropriate style** for the content type
4. **Include working examples** and test them
5. **Submit a pull request** with clear description

### Documentation Issues

If you find issues with the documentation:

1. **Check existing issues** to avoid duplicates
2. **Provide specific details** about the problem
3. **Suggest improvements** when possible
4. **Include context** about your use case

### Style and Formatting

**Markdown**: Use standard Markdown syntax
**Headers**: Use sentence case for headers
**Links**: Use descriptive link text
**Images**: Include alt text for accessibility
**Code**: Use syntax highlighting with language specification

## Deployment

The documentation is automatically built and deployed on:

- **Main branch**: Production deployment
- **Pull requests**: Preview deployments for review

### Manual Deployment

```bash
# Build the site
npm run build

# Deploy to hosting platform
# (specific commands depend on your hosting choice)
```

## Technology Stack

**[Astro](https://astro.build/)**: Static site generator with excellent performance
**[Starlight](https://starlight.astro.build/)**: Documentation theme optimized for technical content
**[Diátaxis](https://diataxis.fr/)**: Documentation methodology for user-centered organization

### Why These Choices?

**Astro**: Fast, modern static site generation with excellent SEO and performance
**Starlight**: Purpose-built for technical documentation with excellent navigation and search
**Diátaxis**: Proven methodology that serves different user mental states effectively

## Maintenance

### Regular Updates

- **Content Review**: Quarterly review of all content for accuracy
- **Link Checking**: Automated checking for broken links
- **Example Testing**: Regular validation of code examples
- **User Feedback**: Incorporate feedback from the community

### Analytics and Monitoring

- **Usage Tracking**: Monitor which content is most valuable
- **Search Analytics**: Understand what users are looking for
- **Performance Monitoring**: Ensure fast loading times
- **User Feedback**: Collect and respond to user input

## Support

For documentation-specific questions:

- **GitHub Issues**: Report bugs or request new content
- **GitHub Discussions**: Ask questions about the documentation
- **Pull Requests**: Contribute improvements directly

For MCPTesta usage questions, see the main project documentation and support channels.

---

*This documentation is built with ❤️ by the MCPTesta community following Diátaxis principles to serve all FastMCP developers effectively.*