> ## Documentation Index
> Fetch the complete documentation index at: https://cona.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation & AI Rules: A Dual Approach

> Understanding CONA documentation strategy and how we balance human-focused docs with AI-guided rules

# Documentation & AI Rules: A Dual Approach

CONA uses a dual approach to maintaining project knowledge and standards:

1. **Human-Focused Documentation** - In the `/docs` directory
2. **AI-Guided Rules** - In the `.cursor/rules` directory

This document explains the reasoning, benefits, and implementation of this dual strategy.

## The Challenge

Development teams face a perennial challenge: maintaining consistent standards while preserving knowledge. Traditional approaches have included:

* Extensive documentation that developers rarely read
* Code reviews that repeatedly address the same issues
* Tribal knowledge that disappears when team members leave

With the introduction of AI coding assistants, a new challenge emerged: **how do we ensure AI understands our unique patterns and standards?**

## Our Solution: A Dual-Track Approach

Rather than treating documentation as one-size-fits-all, we've separated our knowledge management into two distinct but complementary tracks:

### Human-Focused Documentation

Documentation in the `/docs` directory is:

* Rich with context and explanations
* Enhanced with diagrams and visualizations
* Focused on teaching concepts and "why"
* Organized for discovery and learning
* Designed for comprehensive understanding

### AI-Guided Rules

Rules in the `.cursor/rules` directory are:

* Concise and technically precise
* Packed with specific implementation patterns
* Focused on the "how" of implementation
* Organized for retrieval and application
* Designed for consistent execution

## When to Use Which Approach

### Create Human Documentation When:

* Onboarding new team members
* Explaining complex business logic
* Documenting architectural decisions
* Creating step-by-step guides
* Illustrating workflows with diagrams
* Clarifying the reasoning behind patterns

### Create AI Rules When:

* Defining coding standards
* Establishing file structure patterns
* Specifying import conventions
* Standardizing component structures
* Defining API interaction patterns
* Establishing testing requirements

## Areas Requiring Both

Some critical areas should have both human documentation and AI rules:

| Area             | Human Documentation                   | AI Rules                                   |
| ---------------- | ------------------------------------- | ------------------------------------------ |
| Architecture     | System diagrams, rationale, evolution | Implementation patterns, file organization |
| State Management | Decision framework, conceptual model  | Code patterns, specific approaches         |
| Testing          | Strategy, coverage goals, philosophy  | Implementation standards, mock patterns    |
| Performance      | Critical paths, benchmarks, goals     | Optimization techniques, patterns to avoid |

## Implementation Guide

### Creating Human Documentation

1. **Structure:** Use MDX with clear headings and sections
2. **Content:** Include context, reasoning, examples, and diagrams
3. **Location:** Place in the appropriate `/docs` subdirectory
4. **Index Entry:** Add the document to `docs.json` to make it discoverable
5. **Format:** Follow our documentation style guide
6. **Cross-Reference:** Note related AI rules when applicable

> **Important:** All documentation files must be added to `docs.json` to appear in the navigation and be properly indexed for search. Failing to add your document to `docs.json` will make it invisible to users.

### Creating AI Rules

1. **Structure:** Use MDC with proper metadata headers
2. **Content:** Focus on implementation patterns with code examples
3. **Location:** Place in `.cursor/rules` directory
4. **Format:** Follow concise, technically specific language
5. **Metadata:** Include appropriate glob patterns and application settings

## Examples

### Example 1: State Management

**Human Documentation** (in `/docs/core-concepts/state-management.mdx`):

* Visual diagram of state types
* Decision tree for choosing state approaches
* Explanations of when to use URL vs. context state
* Examples with reasoning

**AI Rule** (in `.cursor/rules/state-management.mdc`):

* Specific implementation patterns
* Code snippets showing correct approaches
* Technical specifications for each state type
* Integration details

### Example 2: Testing

**Human Documentation** (in `/docs/guides/testing-strategy.mdx`):

* Overall testing philosophy
* Coverage goals and metrics
* Visual representation of test pyramid
* Examples of good tests with explanations

**AI Rule** (in `.cursor/rules/testing-guidelines.mdc`):

* Directory and file naming conventions
* Implementation patterns for test files
* Mock creation standards
* Technical specifications for assertions

## Benefits of the Dual Approach

This approach offers several key benefits:

1. **Separation of Concerns**: Each type of documentation focuses on what it does best
2. **Reduced Repetition**: No need to make docs technical enough for implementation
3. **Better Adherence**: Standards enforced by AI at the point of creation
4. **Improved Discoverability**: Human docs can focus on learning and discovery
5. **Enhanced Consistency**: Technical details don't get lost in conceptual docs
6. **Complementary Coverage**: Both systems cover what the other might miss

## Maintenance Strategy

To keep both systems aligned:

1. When making significant changes, update both human docs and AI rules
2. Conduct quarterly audits to identify divergence
3. Reference related documentation in rule files
4. Mention rule existence in human documentation
5. Use PR templates that prompt for documentation updates

## Documentation Indexing

To ensure your documentation is discoverable in our documentation system:

1. Add each new document to the `docs.json` file in the root of the `/docs` directory
2. Specify the appropriate title, description, and category
3. Add it to the correct section in the navigation structure

Example entry in `docs.json`:

```json theme={null}
{
  "title": "Documentation & AI Rules",
  "description": "Understanding our dual approach to documentation",
  "path": "guides/documentation-and-rules",
  "category": "guides"
}
```

Without this entry, your documentation will not appear in the navigation menu or search results, making it effectively invisible to team members.

## Conclusion

By separating human-focused documentation from AI-guided rules, we create a more effective knowledge management system. Humans get the context and reasoning they need, while AI gets the precise guidance required to generate code according to our standards.

This dual approach allows us to maintain consistent standards while preserving the knowledge that makes our codebase unique.