# Documentation Guide

Welcome to the **MCP ADR Analysis Server** documentation. Our documentation follows the [Diataxis framework](https://diataxis.fr/) - a systematic approach to technical documentation organized by user intent.

---

## Documentation Structure

### Tutorials (Learning-Oriented)

Step-by-step guides that take you through a series of steps to complete a project. Best for **newcomers** who want to learn by doing.

- [First Steps](./tutorials/01-first-steps.md) - Get started with your first ADR analysis
- [Existing Projects](./tutorials/02-existing-projects.md) - Integrate with an existing codebase
- [Advanced Analysis](./tutorials/03-advanced-analysis.md) - Deep architectural analysis techniques
- [Security-Focused Workflow](./tutorials/security-focused-workflow.md) - Security-first development patterns
- [Team Collaboration](./tutorials/team-collaboration.md) - Working with teams on architectural decisions

### How-To Guides (Task-Oriented)

Practical guides that help you accomplish specific tasks. Best for **practitioners** who know what they want to do.

- [Installation Guide](./how-to-guides/installation-guide.md) - Detailed installation instructions
- [MCP Client Setup](./how-to-guides/mcp-client-compatibility.md) - Configure Claude, Cursor, Cline, and more
- [Firecrawl Integration](./how-to-guides/firecrawl-setup.md) - Enable web content analysis
- [Troubleshooting](./how-to-guides/troubleshooting.md) - Common issues and solutions
- [Deployment Readiness](./how-to-guides/deployment-readiness.md) - Validate deployment readiness

### Reference (Information-Oriented)

Technical descriptions of the machinery and how to operate it. Best for **users** who need to look up specific details.

- [API Reference](./reference/api-reference.md) - Complete tool documentation
- [Comprehensive API Reference](./reference/comprehensive-api-reference.md) - Extended API documentation
- [Analysis Tools](./reference/analysis-tools.md) - Code analysis tool specifications
- [Configuration](./configuration.md) - Environment variables and settings

### Explanation (Understanding-Oriented)

Discussions that clarify and illuminate concepts. Best for **learners** who want to understand the bigger picture.

- [Architecture Overview](./explanation/architecture-overview.md) - System design and components
- [AI Architecture Concepts](./explanation/ai-architecture-concepts.md) - AI integration patterns
- [Self-Learning Architecture](./explanation/self-learning-architecture.md) - Adaptive analysis capabilities

---

## Quick Start Paths

### New to MCP ADR Analysis Server?

1. Read [What is MCP?](../README.md#what-is-mcp) in the README
2. Follow the [First Steps Tutorial](./tutorials/01-first-steps.md)
3. Explore the [API Reference](./reference/api-reference.md)

### Setting Up for Your Team?

1. Review [Architecture Overview](./explanation/architecture-overview.md)
2. Follow the [Installation Guide](./how-to-guides/installation-guide.md)
3. Configure [ADR Aggregator](../README.md#-adr-aggregator-integration-optional) for cross-team visibility

### Troubleshooting Issues?

1. Check the [Troubleshooting Guide](./how-to-guides/troubleshooting.md)
2. Review [MCP Client Compatibility](./how-to-guides/mcp-client-compatibility.md)
3. Search [GitHub Issues](https://github.com/tosin2013/mcp-adr-analysis-server/issues)

---

## About Diataxis

The Diataxis framework recognizes that documentation serves different purposes for different users at different times:

| Type              | Purpose       | User Need                  |
| ----------------- | ------------- | -------------------------- |
| **Tutorials**     | Learning      | "I want to learn"          |
| **How-To Guides** | Goals         | "I want to accomplish X"   |
| **Reference**     | Information   | "I need to know about Y"   |
| **Explanation**   | Understanding | "I want to understand why" |

By organizing our documentation this way, we help you find exactly what you need, when you need it.

---

## Contributing to Documentation

Found an issue or want to improve our docs? See the [Contributing Guide](./community/CONTRIBUTING.md) for how to submit changes.
