Cómo leer esta guía

Esta guía cubre dos cosas muy distintas: cómo se usa el producto y cómo se integra con otros sistemas. Escribir las dos igual perjudica a las dos, así que cada artículo declara para quién está escrito.

Las tres etiquetas

Debajo del título de cada artículo hay una etiqueta. No es decorativa: decide el lenguaje del artículo.

Uso diario

Para quien hace el trabajo: asesores, editores de inventario, la mesa financiera.

• Segunda persona: «abre», «marca», «sube».
• Cero vocabulario interno. Ninguna tabla, ninguna clave de permiso, ningún endpoint.
• Dice qué hacer y qué pasa después.
• Un concepto se explica con lo que se ve en pantalla, no con cómo está construido.

Configuración

Para quien administra el espacio de trabajo: dueño, administrador, responsable de área.

• Sigue siendo lenguaje llano.
• Sí nombra roles, claves de permiso y ajustes, porque esos son los objetos que esa persona maneja todos los días.
• Explica las consecuencias de un ajuste, no solo dónde está el interruptor.

Avanzado

Para quien integra el producto: desarrolladores, IT.

• Endpoints, llaves, cabeceras, códigos de estado, ejemplos de código.
• Presupone conocimientos de desarrollo.
• Es la única etiqueta que asume vocabulario de programación.

Cómo elegimos la etiqueta de un artículo

Por el sujeto que describe, no por quién nos imaginamos leyéndolo:

Si el artículo describe…	Etiqueta
Una pantalla que se usa para trabajar	Uso diario
Un interruptor que cambia el comportamiento para todos	Configuración
Un contrato entre sistemas	Avanzado

Un mismo tema puede aparecer en dos artículos con dos etiquetas. Comisiones se explica dos veces: cómo se cobra y cómo se lee la pantalla (uso diario), y cómo se configura el reparto (configuración). No es duplicación: son dos preguntas distintas y dos lectores distintos.

Qué no hace esta guía

• No explica por qué está construido así por dentro. Ese razonamiento vive en la documentación técnica del repositorio, que es donde lo busca quien va a tocar el código. Aquí queda la consecuencia.
• No inventa capturas de pantalla. Cuando una pantalla se describe, se describe por lo que hace.

Convenciones de escritura

• Español, igual que el producto. El producto también habla inglés, y esta guía seguirá.
• «Espacio de trabajo», nunca workspace.
• Los nombres de las secciones se escriben como aparecen en el menú: Negocios, Prospectos, Comisiones.
• Cuando hay dos términos que se confunden, el artículo lo dice explícitamente. Ver Glosario.