---
description: Reglas y mejores prácticas para la creación y mantenimiento de documentación
globs: "**/*.md"
alwaysApply: false
---
# Estándares de Documentación

## Principios Fundamentales

### Claridad y Estructura
- Usar lenguaje simple y directo
- Mantener párrafos concisos
- Seguir estructura jerárquica (general a específico)
- Incluir tabla de contenidos para documentos largos

### Contenido
- Proporcionar ejemplos prácticos
- Documentar casos de uso reales
- Incluir código cuando sea relevante
- Explicar conceptos complejos paso a paso

## Estructura Recomendada

```markdown
# Título del Documento

## Descripción General
Breve descripción del propósito y alcance.

## Tabla de Contenidos
- [Sección 1](mdc:#seccion-1)
- [Sección 2](mdc:#seccion-2)

## Contenido Principal
### Sección 1
Contenido organizado y claro...

### Sección 2
Más contenido con ejemplos...

## Ejemplos de Uso
\```typescript
// Ejemplo de código
\```

## Referencias
- Enlaces relevantes
- Documentación relacionada
```

## Tipos de Documentación

### 1. Documentación Técnica
- Incluir tipos y parámetros
- Documentar efectos secundarios
- Proporcionar ejemplos de código
- Explicar casos límite

### 2. Documentación de Usuario
- Usar lenguaje accesible
- Incluir capturas de pantalla
- Proporcionar pasos claros
- Documentar solución de problemas

### 3. Documentación de Arquitectura
- Incluir diagramas relevantes
- Explicar decisiones de diseño
- Documentar dependencias
- Describir flujos de datos

## Checklist de Calidad

- [ ] ¿El documento tiene una estructura clara?
- [ ] ¿Los ejemplos son actuales y relevantes?
- [ ] ¿Se incluyen casos de uso reales?
- [ ] ¿La documentación es concisa y directa?
- [ ] ¿Se han documentado los edge cases?
- [ ] ¿Los enlaces funcionan correctamente?
- [ ] ¿El contenido está actualizado?

## Ejemplos

### Buena Documentación
```markdown
# Servicio de Autenticación

## Descripción
Gestiona la autenticación de usuarios mediante JWT.

## Uso
\```typescript
import { AuthService } from '@/services/auth';

const auth = new AuthService();
await auth.login({ email, password });
\```

## API
| Método | Parámetros | Retorno | Descripción |
|--------|------------|---------|-------------|
| login | LoginCredentials | Promise<User> | Autentica usuario |

## Manejo de Errores
- InvalidCredentials: Credenciales incorrectas
- UserLocked: Usuario bloqueado
```

### Documentación Mejorable
```markdown
# Auth

login() - hace login
logout() - hace logout

ejemplo:
auth.login()
auth.logout()
```

## Referencias
@file .docs/documentation-best-practices.md
@file README.md