​

Style Guide — Docs de Trébol

​

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

​

DRY (no repitas información)

• Si un concepto se explica en >1 página, vive en una sola y las demás enlazan con <Card>.
• 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 <CodeGroup> 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

---
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.