@damenor/agent-docs 0.1.1 → 0.4.0

package/templates/modules/agents/.agents/skills/doc-scaffold/references/diataxis-quick-ref.md

@@ -1,149 +1,149 @@
 ---
-created: "2024-01-15"
+created: '2024-01-15'
 status: active
 type: reference
-tags: [diataxis, framework, documentacion, referencia]
+tags: [diataxis, framework, documentation, reference]
 ---
 
-# Diátaxis — Referencia Rápida
+# Diátaxis — Quick Reference
 
-## Los 4 Cuadrantes
+## The 4 Quadrants
 
-Diátaxis clasifica la documentación en 4 tipos según dos ejes:
+Diátaxis classifies documentation into 4 types along two axes:
 
-- **Eje horizontal**: Estudio (aprender) vs Trabajo (aplicar)
-- **Eje vertical**: Práctico (acción) vs Teórico (conocimiento)
+- **Horizontal axis**: Study (learn) vs Work (apply)
+- **Vertical axis**: Practical (action) vs Theoretical (knowledge)
 
 ```
-                    │ Práctico (acción)
+                    │ Practical (action)
                     │
          Tutorial   │   How-to
-      (Aprender     │  (Aplicar
-       haciendo)    │   soluciones)
+      (Learning     │  (Applying
+       by doing)    │   solutions)
                     │
 ────────────────────┼────────────────────
                     │
-      Explicación   │  Referencia
-     (Entender el   │ (Buscar
-       porqué)      │  información)
+      Explanation   │  Reference
+     (Understanding │ (Looking up
+        why)        │  information)
                     │
-                    │ Teórico (conocimiento)
+                    │ Theoretical (knowledge)
 ```
 
 ### Tutorial
 
-- **Orientación**: Aprendizaje
-- **Propósito**: Guiar al principiante paso a paso para adquirir una habilidad
-- **Tono**: Didáctico, paciente, alentador
-- **Ejemplo**: "Tu primera API con Express.js" — el usuario aprende mientras construye
+- **Orientation**: Learning
+- **Purpose**: Guide the beginner step by step to acquire a skill
+- **Tone**: Didactic, patient, encouraging
+- **Example**: "Your first Express.js API" — the user learns while building
 
-### How-to (Guía práctica)
+### How-to
 
-- **Orientación**: Práctica
-- **Propósito**: Resolver un problema específico concreto
-- **Tono**: Directo, asume conocimiento previo
-- **Ejemplo**: "Cómo configurar autenticación con JWT" — el usuario ya sabe Express, necesita JWT
+- **Orientation**: Practice
+- **Purpose**: Solve a specific concrete problem
+- **Tone**: Direct, assumes prior knowledge
+- **Example**: "How to configure JWT authentication" — the user already knows Express, needs JWT
 
-### Referencia
+### Reference
 
-- **Orientación**: Información
-- **Propósito**: Describir la maquinaria de forma factual y completa
-- **Tono**: Neutral, estructurado, sin narrativa
-- **Ejemplo**: "API de endpoints" — tablas con métodos, parámetros, respuestas
+- **Orientation**: Information
+- **Purpose**: Describe the machinery in a factual and complete way
+- **Tone**: Neutral, structured, no narrative
+- **Example**: "API endpoints" — tables with methods, parameters, responses
 
-### Explicación
+### Explanation
 
-- **Orientación**: Comprensión
-- **Propósito**: Aclarar el porqué, dar contexto, conectar conceptos
-- **Tono**: Discursivo, analítico
-- **Ejemplo**: "Por qué elegimos event-sourcing" — contexto histórico, alternativas, trade-offs
+- **Orientation**: Understanding
+- **Purpose**: Clarify why, provide context, connect concepts
+- **Tone**: Discursive, analytical
+- **Example**: "Why we chose event-sourcing" — historical context, alternatives, trade-offs
 
-## Cuándo Usar Cada Tipo
+## When to Use Each Type
 
-| Situación | Tipo | Carpeta |
-|-----------|------|---------|
-| Usuario nuevo quiere empezar | Tutorial | `tutorials/` |
-| Usuario tiene un problema específico | How-to | `how-to/` |
-| Usuario necesita consultar un detalle | Referencia | `reference/` |
-| Usuario pregunta "¿por qué?" | Explicación | `explanation/` |
-| Onboarding de nuevo dev | Tutorial | `tutorials/` |
-| Configurar algo que ya se conoce | How-to | `how-to/` |
-| Buscar parámetros de una función | Referencia | `reference/` |
-| Entender una decisión arquitectónica | Explicación | `explanation/` |
+| Situation                            | Type        | Folder         |
+| ------------------------------------ | ----------- | -------------- |
+| New user wants to get started        | Tutorial    | `tutorials/`   |
+| User has a specific problem          | How-to      | `how-to/`      |
+| User needs to look up a detail       | Reference   | `reference/`   |
+| User asks "why?"                     | Explanation | `explanation/` |
+| New dev onboarding                   | Tutorial    | `tutorials/`   |
+| Configure something already known    | How-to      | `how-to/`      |
+| Look up function parameters          | Reference   | `reference/`   |
+| Understand an architectural decision | Explanation | `explanation/` |
 
-## Árbol de Decisión
+## Decision Tree
 
 ```
-¿El lector necesita aprender algo nuevo desde cero?
-├── SÍ → ¿Se aprende mejor haciendo?
-│   ├── SÍ → TUTORIAL → tutorials/
-│   └── NO → EXPLICACIÓN → explanation/
-└── NO → ¿Necesita resolver un problema práctico?
-    ├── SÍ → ¿Necesita pasos concretos?
-    │   ├── SÍ → HOW-TO → how-to/
-    │   └── NO → EXPLICACIÓN → explanation/
-    └── NO → ¿Necesita buscar información específica?
-        ├── SÍ → REFERENCIA → reference/
-        └── NO → Replantear la necesidad
+Does the reader need to learn something new from scratch?
+├── YES → Is it best learned by doing?
+│   ├── YES → TUTORIAL → tutorials/
+│   └── NO → EXPLANATION → explanation/
+└── NO → Do they need to solve a practical problem?
+    ├── YES → Do they need concrete steps?
+    │   ├── YES → HOW-TO → how-to/
+    │   └── NO → EXPLANATION → explanation/
+    └── NO → Do they need specific information?
+        ├── YES → REFERENCE → reference/
+        └── NO → Re-evaluate the need
 ```
 
-## Ejemplos por Tipo en Proyectos Web
+## Examples by Type in Web Projects
 
 ### Tutorial (tutorials/)
 
-| Título | Qué enseña |
-|--------|------------|
-| `quick-start.md` | Crear el primer endpoint, levantar el proyecto |
-| `first-component.md` | Crear un componente React/Vue desde cero |
-| `database-setup.md` | Configurar la base de datos por primera vez |
-| `deploy-guide.md` | Hacer el primer deploy paso a paso |
+| Title                | What it teaches                               |
+| -------------------- | --------------------------------------------- |
+| `quick-start.md`     | Create the first endpoint, launch the project |
+| `first-component.md` | Create a React/Vue component from scratch     |
+| `database-setup.md`  | Set up the database for the first time        |
+| `deploy-guide.md`    | Make the first deployment step by step        |
 
 ### How-to (how-to/)
 
-| Título | Qué resuelve |
-|---------|-------------|
-| `add-auth.md` | Agregar autenticación a una API existente |
-| `custom-middleware.md` | Crear middleware personalizado |
-| `migrate-database.md` | Ejecutar una migración de base de datos |
-| `configure-ci.md` | Configurar pipeline de CI/CD |
-| `add-new-endpoint.md` | Agregar un nuevo endpoint REST |
-| `debug-connection.md` | Diagnosticar problemas de conexión |
-
-### Referencia (reference/)
-
-| Título | Qué documenta |
-|---------|-------------|
-| `api.md` | Todos los endpoints: método, ruta, params, respuesta |
-| `configuration.md` | Todas las variables de configuración y sus valores |
-| `cli.md` | Todos los comandos CLI con flags y ejemplos |
-| `events.md` | Todos los eventos del sistema con payload |
-| `errors.md` | Códigos de error con significado y resolución |
-
-### Explicación (explanation/)
-
-| Título | Qué explica |
-|---------|------------|
-| `architecture.md` | Visión general de la arquitectura y sus capas |
-| `authentication-flow.md` | Cómo funciona el flujo de auth end-to-end |
-| `database-design.md` | Por qué se eligió el esquema actual |
-| `caching-strategy.md` | Estrategia de caché y sus trade-offs |
-| `adr/001-event-sourcing.md` | Decisión arquitectónica con contexto |
-
-## Tabla Rápida: Objetivo del Usuario → Tipo → Ubicación
-
-| Objetivo del usuario | Tipo de doc | Ubicación |
-|---------------------|------------|-----------|
-| "Quiero aprender a usar esto" | Tutorial | `tutorials/` |
-| "Quiero hacer X cosa específica" | How-to | `how-to/` |
-| "Necesito consultar un dato" | Referencia | `reference/` |
-| "Quiero entender por qué es así" | Explicación | `explanation/` |
-| "¿Cómo se decide la arquitectura?" | ADR | `docs/adr/` |
-| "¿Qué significa este término?" | CONTEXT | `docs/CONTEXT.md` |
-| "¿Cómo se ve el sistema?" | Diseño | `DESIGN.md` |
-| "¿Qué cambió en cada versión?" | Changelog | `CHANGELOG.md` |
-
-## Regla de Oro
-
-**Un documento = Un propósito = Un tipo Diátaxis.**
-
-Si un documento intenta ser tutorial Y referencia al mismo tiempo, ninguno de los dos funciona bien. Separar es mejorar.
+| Title                  | What it solves                        |
+| ---------------------- | ------------------------------------- |
+| `add-auth.md`          | Add authentication to an existing API |
+| `custom-middleware.md` | Create custom middleware              |
+| `migrate-database.md`  | Run a database migration              |
+| `configure-ci.md`      | Set up CI/CD pipeline                 |
+| `add-new-endpoint.md`  | Add a new REST endpoint               |
+| `debug-connection.md`  | Diagnose connection issues            |
+
+### Reference (reference/)
+
+| Title              | What it documents                              |
+| ------------------ | ---------------------------------------------- |
+| `api.md`           | All endpoints: method, route, params, response |
+| `configuration.md` | All configuration variables and their values   |
+| `cli.md`           | All CLI commands with flags and examples       |
+| `events.md`        | All system events with payload                 |
+| `errors.md`        | Error codes with meaning and resolution        |
+
+### Explanation (explanation/)
+
+| Title                       | What it explains                     |
+| --------------------------- | ------------------------------------ |
+| `architecture.md`           | Architecture overview and its layers |
+| `authentication-flow.md`    | How auth flow works end-to-end       |
+| `database-design.md`        | Why the current schema was chosen    |
+| `caching-strategy.md`       | Caching strategy and its trade-offs  |
+| `adr/001-event-sourcing.md` | Architectural decision with context  |
+
+## Quick Table: User Goal → Type → Location
+
+| User goal                                 | Doc type    | Location          |
+| ----------------------------------------- | ----------- | ----------------- |
+| "I want to learn how to use this"         | Tutorial    | `tutorials/`      |
+| "I want to do X specific thing"           | How-to      | `how-to/`         |
+| "I need to look up something"             | Reference   | `reference/`      |
+| "I want to understand why it's like this" | Explanation | `explanation/`    |
+| "How was the architecture decided?"       | ADR         | `docs/adr/`       |
+| "What does this term mean?"               | CONTEXT     | `docs/CONTEXT.md` |
+| "What does the system look like?"         | Design      | `DESIGN.md`       |
+| "What changed in each version?"           | Changelog   | `CHANGELOG.md`    |
+
+## Golden Rule
+
+**One document = One purpose = One Diátaxis type.**
+
+If a document tries to be both a tutorial AND a reference at the same time, neither works well. Separate to improve.