Guías de estilo

Configuración regional: es-ES

Caso de uso: Producto SaaS B2B – Centro de ayuda e interfaz de usuario

# Guía de estilo: ES-ES – Artículos del centro de ayuda

## 1. Propósito y alcance

Esta guía de estilo define los estándares de escritura para toda la **documentación del Centro de ayuda** en **español (España)**.

Se aplica a:

- Artículos con instrucciones  
- Explicaciones de características  
- Guías de solución de problemas  
- Entradas de preguntas frecuentes (FAQ)  

**Audiencia:** usuarios profesionales de SaaS en roles técnicos y de negocio  
**Objetivo:** ayudar a los usuarios a completar tareas de manera rápida, segura y sin confusiones.

---

## 2. Voz y tono

El contenido del centro de ayuda debe sonar:

- **Claro y profesional**
- **Solidario y enfocado en soluciones**
- **Seguro y sin ser promocional**

Escribimos como una guía que ayuda a los usuarios a tener éxito, no como un texto publicitario.

### Principios de tono

| Qué Hacer | Qué no hacer |
|---|------|
| Ser calmado y directo | Ser demasiado informal o charlatán |
| Enfocarse en los próximos pasos | Enfocarse solo en lo que salió mal |
| Usar un lenguaje neutral | Usar sarcasmo o humor |

**Ejemplos**

- ✅ «Si la conexión falla, verifica tu token de API y vuelve a intentarlo».  
- ❌ «Tu token es incorrecto. Corrígelo».

---

## 3. Gramática y estilo de escritura

### 3.1 Dirígete directamente al lector

Usa la formula de tratamiento informal **tú** para hacer que las instrucciones sean más claras.

- ✅ «Puedes gestionar usuarios desde la página de Admin».  
- ❌ «Usted puede gestionar usuarios desde la página de Admin»

---

### 3.2 Usa más la voz activa

La voz activa es más corta y más fácil de seguir.

- ✅ «Selecciona **Guardar cambios**».  
- ❌ «Los cambios deben ser guardados».

---

### 3.3 Mantén las oraciones concisas

- Intenta que la longitud sea de **25 palabras o menos**
- Usa una idea principal por oración
- Divide explicaciones largas en pasos o viñetas

---

### 3.4 Usa un lenguaje sencillo

Evita la complejidad innecesaria.

- ✅ «Inicia un nuevo proyecto».  
- ❌ «Inicia la creación de un nuevo proyecto».

---

## 4. Terminología y consistencia

### 4.1 Usa términos aprobados

Usa los nombres de productos y características exactamente como están definidos.

- Mantén la capitalización consistente  
- No inventes sinónimos para conceptos clave  

**Ejemplo**

- ✅ «espacio de trabajo».  
- ❌ «espacio», «área de proyecto» o «entorno».

---

### 4.2 Define acrónimos poco comunes

Los términos comunes (API, URL) no necesitan definición.  
Los acrónimos internos o poco comunes deben explicarse en su primer uso.

- ✅ «Autenticación de un solo paso (SSO)».  
- ❌ «SSO» sin contexto.

---

### 4.3 Convenciones del español de España

Usa siempre **terminología propia del español de España**.

- ✅ «teléfono», «ordenador»  
- ❌ «celular», «computadora»

---

## 5. Estándares de formato y Markdown

### 5.1 Encabezados

Usa encabezados claros y basados en tareas.

- ✅ «Restablece tu contraseña».  
- ❌ «Descripción general del proceso de restablecimiento de contraseña».

Jerarquía de encabezados:

- `#` Título del artículo  
- `##` Secciones principales  
- `###` Subsecciones solo cuando sea necesario  

---

### 5.2 Listas

Usa listas numeradas para secuencias:

1. Abre **Configuración**  
2. Selecciona **Facturación**  
3. Elige **Cambiar plan**  

Usa guiones o listas para mostrar las opciones:

- Los administradores pueden gestionar usuarios  
- Los editores pueden actualizar contenido  

---

### 5.3 Elementos de la interfaz de usuario

Formatea las etiquetas de la interfaz de usuario de manera consistente:

- Botones: **negrita**
- Rutas de navegación: usa flechas

Ejemplo:

Ir a **Configuración → Facturación → Cambiar plan**.

---

### 5.4 Enlaces

Los enlaces deben describir el destino.

- ✅ «Mira la guía de facturación».  
- ❌ «Haz clic aquí».

---

## 6. Estructura estándar del artículo

Cada artículo del centro de ayuda debe seguir esta estructura:

### 1. Resumen

Comienza con 1-2 oraciones explicando el resultado.

> Este artículo explica cómo cambiar tu plan de suscripción.

---

### 2. Requisitos previos (opcional)

Enumera los requisitos de antemano.

- Permisos de admin  
- Suscripción activa  

---

### 3. Instrucciones paso a paso

Los pasos deben ser:

- Orientados a la acción  
- Una acción por paso  
- Escrito como comandos  

Ejemplo:

1. Ve a **Configuración**.  
2. Selecciona **Facturación**.  
3. Elige **Cambiar plan**.  

---

### 4. Resultado esperado

Dile al usuario qué debería suceder.

> Tu nuevo plan entra en vigor inmediatamente después de la confirmación.

---

### 5. Próximos pasos (opcional)

Proporciona acciones o enlaces relacionados.

- Gestionar facturas  
- Actualizar método de pago  

---

## 7. Solución de problemas y errores

### 7.1 Se tranquilizador

- ✅ «No pudimos conectar. Por favor, inténtalo de nuevo».  
- ❌ «Conexión fallida. Error crítico».

---

### 7.2 Céntrate en encontrar soluciones

Siempre incluye lo que el usuario debe hacer a continuación.

- Verificar credenciales  
- Confirmar permisos  
- Contactar con soporte si es necesario  

---

### 7.3 Nunca culpes al usuario

Evita expresiones como:

- «Hiciste algo mal»  
- «Entrada inválida» (sin explicación)

En su lugar, di lo siguiente:

> «El token puede estar expirado. Genera uno nuevo y vuelve a intentarlo».

---

## 8. Resumen de lo que debes hacer y de lo que no debes hacer

### Lo que debes hacer

- Escribir contenido enfocado en tareas y basado en pasos  
- Usar terminología consistente  
- Mantener las oraciones cortas y directas  
- Usar encabezados y enlaces descriptivos  
- Mantener un tono calmado y de apoyo  

### Lo que no debes hacer

- Agregar lenguaje de marketing  
- Usar modismos o jerga  
- Mezclar términos para el mismo concepto  
- Culpar al usuario en la resolución de problemas  
- Escribir párrafos largos sin estructura  

---

## Ejemplo (de cómo se debería hacer bien)

Para cambiar tu plan:

1. Ve a **Configuración → Facturación**  
2. Selecciona **Cambiar plan**  
3. Elige una opción y selecciona **Confirmar**