> ## Documentation Index > Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # STYLE GUIDE # Style Guide — Docs de Trébol Referencia única para escribir y revisar documentación. Citado por los skills de revisión automática en `.claude/skills/`. ## Idioma y tono * **Idioma**: español latam. No mezclar con inglés salvo términos técnicos sin equivalente común (`webhook`, `endpoint`, `request`, `response`). * **Persona**: tutea al lector ("tú"), formal-cercano. Evita "usted" y evita coloquialismos. * **Tiempo verbal**: presente del indicativo ("el endpoint devuelve…", no "el endpoint devolverá…"). * **Voz**: activa. Evita pasiva ("la verificación es creada por…" → "tú creas la verificación…"). * **Oraciones**: cortas. Si una oración pasa de 25 palabras, divídela. ## Títulos y encabezados * **Sentence case**: solo la primera letra mayúscula y nombres propios. Ej. `## Crear una verificación`, no `## Crear Una Verificación`. * **Jerarquía**: un solo `#` por archivo (el frontmatter `title` lo cubre). Usa `##` y `###` para secciones. ## Naming de archivos * `lowercase-con-guiones.mdx`. Sin acentos en filename. * Refleja el path en `docs.json`. ## Naming en `api-reference/openapi.yaml` * **Fields/properties**: `snake_case` (ej. `flow_id`, `friendly_name`, `key_people`, `client_item_type`). * **Contrato existente**: conserva `triggeredSideEffects` en la respuesta de `PUT /verification-items/{id}`. El backend usa ese nombre; cambiarlo solo en la documentación rompería el contrato de los clientes. * **operationId**: `camelCase` con verbo + sustantivo (ej. `crearNuevaVerificacion`, `obtenerEmpresaPorTag`). Verbo en español. * **Tags**: español, sentence case (ej. `Creacion de Verificacion`, `Gestión de Webhooks`). * **Descriptions**: español, no vacías. Una oración mínimo por field y por endpoint. * **Autoexplicativo**: el nombre del field debe revelar su función sin abreviaturas opacas (`nm`, `data1`, `info` están prohibidos). Si el dominio lo requiere (`rfc`, `nit`), agrega contexto en `description`. * **No duplicar significado**: antes de crear `display_name` revisa si ya existe `friendly_name`. Antes de `created_date` revisa `created_at`. * La regla prohíbe **dos nombres para el mismo concepto**, no dos nombres parecidos para conceptos distintos. Cuando la diferencia sea real pero no evidente, documéntala en la `description` del schema y anótala aquí. * **Excepción decidida (2026-09-01): `FindingsRunConflict.error_code` no se unifica con `ErrorResponse.code`.** No nombran lo mismo. `code` es la clase genérica del error (`VALIDATION_ERROR`, `NOT_FOUND`, en `SCREAMING_SNAKE`) y viaja en un cuerpo con `success: false`; `error_code` es la razón de dominio por la que una corrida no procede (`pending_documents`, `recently_run`, en minúsculas), en un cuerpo sin `success`. Unificarlos obligaría a meter razones de dominio en el enum genérico, o a que un mismo field cargue dos vocabularios. Además `error_code` ya es contrato vivo del backend. No volver a proponer el cambio sin cambiar también BV y la webapp. ## Componentes Mintlify — qué usar y cuándo | Caso de uso | Componente | | ------------------------------------------- | ----------------------------------------------------- | | Listado de pasos secuenciales | `` con `` | | Comparar variantes (país, lenguaje, método) | `` con `` | | Ejemplos de código en varios lenguajes | `` (mínimo curl + 1 cliente) | | Parámetro de request | `` | | Campo de response | `` | | Sección larga colapsable | `` con `` | | Navegación a sub-páginas | `` con `` linkeada | | Aviso importante | ``, ``, ``, `` (según tono) | Evita tablas markdown puras cuando un componente Mintlify expresa mejor la intención (sobre todo para fields de API → ``). ## DRY (no repitas información) * Si un concepto se explica en >1 página, **vive en una sola** y las demás enlazan con ``. * Cuando consolides páginas, agrega un `redirect` en `docs.json` para no romper enlaces externos. * Caso vivo a evitar: las "3 formas" (clasificación / validación / extracción) están explicadas en `producto/como-funciona.mdx` **y** repetidas en `guia-devs/crear-verificaciones/via-api/forma-*.mdx`. Mantén la explicación conceptual en un solo lugar. ## Ejemplos de código * Usa siempre `` con al menos `curl` + un cliente (JavaScript o Python). Tres es mejor. * Cada ejemplo debe ser ejecutable: incluye headers (`x-api-key`), URL completa, payload válido. * Comenta los valores que el lector debe sustituir (`YOUR_API_KEY`, `verification_id`). ## Enlaces * **Internos**: rutas relativas que matchean `docs.json` (ej. `/guia-devs/conectarse`, no `https://docs.gotrebol.com/...`). * **Externos**: HTTPS siempre. * Antes de mergear, verifica que ningún enlace interno quede roto tras renombrar archivos. ## Frontmatter de páginas ```yaml theme={"dark"} --- title: "Crear una verificación" description: "Cómo iniciar una nueva verificación vía API." --- ``` * `title` y `description` siempre presentes. * `description` ≤ 160 caracteres (SEO). ## Commits y PRs * Convencional commits con ticket (ya en `CRUSH.md`): `feat(TICKET-123): …`. * Un PR por iniciativa. PRs gigantes son difíciles de revisar.