Saltar al contenido principal
La buena documentación técnica tiene un solo trabajo: ayudar a los usuarios a lograr un objetivo y volver a su trabajo. Las decisiones de estilo y tono apoyan ese objetivo o se interponen en el camino. Una redacción clara y consistente genera confianza en el usuario. Una redacción inconsistente o poco clara crea fricción y erosiona la confianza en tu producto. Esta guía cubre los principios fundamentales detrás de la redacción técnica efectiva, con orientación práctica sobre cómo aplicarlos.

​
Escribe en segunda persona

Dirígete a los usuarios directamente como “tú”. La segunda persona hace que las instrucciones sean más fáciles de seguir y mantiene el enfoque en lo que los usuarios están haciendo en lugar de lo que hace el producto. 
<!-- Segunda persona (preferido) -->
Puedes configurar el tiempo de espera en tu archivo de configuración.

<!-- Tercera persona (evitar) -->
Los usuarios pueden configurar el tiempo de espera en el archivo de configuración.
La segunda persona también ayuda a detectar la voz pasiva: cuando escribes “tú”, te ves obligado a decir quién hace qué.

​
Usa la voz activa

La voz activa hace que las oraciones sean más cortas y claras. En la voz pasiva, el sujeto recibe la acción. En la voz activa, el sujeto la realiza. 
<!-- Activa -->
La API devuelve un error cuando el token expira.

<!-- Pasiva -->
Se devuelve un error cuando el token ha expirado.
La voz pasiva no siempre es incorrecta. Es apropiada cuando el actor es desconocido o no es importante. Pero la voz pasiva como hábito predeterminado hace que la documentación sea más difícil de leer. Una prueba rápida: si puedes agregar “por zombis” después del verbo, la oración es pasiva. “Se devuelve un error [por zombis]” es pasiva. “La API devuelve [por zombis] un error” es activa.

​
Mantén las oraciones y los párrafos cortos

La documentación se escanea más de lo que se lee. Las oraciones largas y los párrafos densos ralentizan a los usuarios cuando intentan encontrar una respuesta específica. Directrices:
  • Apunta a oraciones de menos de 25 palabras
  • Una idea por oración
  • De dos a cuatro oraciones por párrafo
  • Divide las listas de pasos con secuencias numeradas, no con prosa continua
Si una oración necesita múltiples comas o puntos y comas para mantenerse unida, probablemente pueda dividirse en dos oraciones.

​
Usa encabezados que coincidan con la intención del usuario

Los encabezados organizan la página tanto para humanos como para motores de búsqueda. Escríbelos para responder la pregunta que un usuario podría tener, no para etiquetar un tema desde la perspectiva del producto. 
<!-- Orientado a la intención (mejor) -->
## Cómo configurar la autenticación

<!-- Etiqueta de tema (más débil) -->
## Configuración de autenticación
Usa mayúscula solo al inicio de la oración para todos los encabezados (“Primeros pasos”, no “Primeros Pasos”). No saltes niveles de encabezado—ve de H2 a H3, no de H2 a H4. En la documentación de Mintlify, el H1 de la página se genera automáticamente a partir de la propiedad title: del frontmatter. No agregues un H1 manual en el cuerpo.

​
Usa terminología consistente

Elige un término para cada concepto y úsalo en todas partes. Alternar entre “API key”, “API token” y “access token” para describir lo mismo obliga a los usuarios a detenerse y preguntarse si te refieres a lo mismo. Cuando introduzcas un término por primera vez, defínelo en el lugar en vez de enlazar a otra página. 
<!-- Definir en contexto -->
Cada solicitud requiere una API key—un token único que identifica tu cuenta.

<!-- No asumas conocimiento previo -->
Cada solicitud requiere una API key.
Si tu producto tiene nombres específicos para las cosas (objetos, acciones, elementos de UI), usa esos nombres exactamente como aparecen en el producto. Capitalízalos de forma consistente.

​
Calibra el tono según tu audiencia y tipo de contenido

El tono debe coincidir con lo que los usuarios intentan hacer. Una guía de primeros pasos para nuevos usuarios se beneficia de un tono más cálido y alentador. Una referencia de API para desarrolladores experimentados se beneficia de la densidad y precisión por encima de la calidez. Algunos principios que se aplican a todos los tipos de contenido:
  • Sé directo sin ser brusco. “Haz clic en Guardar” es mejor que “Por favor haz clic en el botón Guardar cuando estés listo para continuar.”
  • Evita las frases de relleno. “Vale la pena señalar que”, “Con el fin de”, “Ten en cuenta que” y “Simplemente” agregan palabras sin agregar significado.
  • No editorialices. “Esta es una función poderosa” es una opinión. Documenta lo que hace, no lo impresionante que es.
  • Usa el vocabulario de tus usuarios. Si tus usuarios lo llaman “webhook”, no lo llames “event callback” en la documentación. Usa la palabra que ya están buscando.

​
Evita errores comunes

​
Jerga y terminología interna

Los equipos desarrollan abreviaturas que los usuarios nunca encuentran. Revisa el contenido nuevo en busca de términos que serían desconocidos para alguien que ve tu producto por primera vez.

​
Capitalización inconsistente

Decide si los nombres de las funciones de tu producto van en mayúsculas (“el Dashboard”, “el API Explorer”) y aplícalo de forma consistente. La capitalización inconsistente indica falta de atención al detalle.

​
Coloquialismos

Las frases informales y los modismos son más difíciles de traducir y más difíciles de interpretar para hablantes no nativos de inglés. La documentación que llega a una audiencia internacional se beneficia de un lenguaje simple y directo.

​
Errores de ortografía y gramática

Incluso unos pocos errores reducen la credibilidad. Indican que el contenido no ha sido revisado cuidadosamente, lo que hace que los usuarios se pregunten si el contenido técnico es igualmente poco confiable.

​
Aplica estándares con herramientas

Los principios de escritura solo perduran si son parte de un flujo de trabajo repetible. Algunas formas de automatizar su cumplimiento:
  • Vale: Un linter para prosa que verifica contra reglas de estilo configurables. Puedes escribir reglas que apliquen tu propia terminología, señalen la voz pasiva o detecten errores comunes.
  • Verificaciones de CI: Ejecuta Vale u otros linters en cada pull request para que los problemas de estilo se detecten antes de que el contenido se fusione.
  • Guías de estilo existentes: En lugar de escribir reglas desde cero, comienza con una guía establecida. La Google Developer Documentation Style Guide, la Microsoft Style Guide y la Splunk Style Guide son todas gratuitas y ampliamente utilizadas.
Usa un workflow para ejecutar una auditoría de estilo de forma programada o cada vez que se envíen cambios a tu repositorio de documentación.

​
Preguntas frecuentes

Ajusta la formalidad a tu audiencia y contexto de producto. Las herramientas para desarrolladores pueden ser directas y concisas—omite las cortesías y ve directo al código. La documentación para usuarios menos técnicos o productos empresariales a menudo se beneficia de un tono más cálido que anticipe la confusión. En cualquier caso, evita el lenguaje corporativo rígido. “Utilizar” no agrega precisión sobre “usar”. Escribe como un colega experto explicaría algo, no como un documento legal lo describiría.
Cuando el actor es desconocido, irrelevante, o cuando enfatizar el resultado es más importante que quién lo causa. “La solicitud se valida antes de procesarse” está bien si estás describiendo lo que le sucede a una solicitud, no quién la valida. La voz pasiva se convierte en un problema cuando oculta quién es responsable de una acción que el usuario necesita realizar.
Identifica la audiencia principal de cada página y escribe para ella. Una guía de primeros pasos debe asumir un conocimiento previo mínimo. Una referencia de API debe asumir que el lector sabe cómo funcionan las APIs. El error es intentar servir a ambos en la misma página—agregar contexto para principiantes en una página de referencia ralentiza a los expertos, y asumir conocimiento experto en un tutorial pierde a los principiantes. Si realmente tienes dos audiencias distintas, considera tipos de contenido separados para cada una. Consulta Tipos de contenido para orientación.
Mantén una lista de terminología—una tabla simple de términos preferidos y términos a evitar. Compártela con todos los que contribuyen a la documentación y revísala durante la revisión. Vale puede aplicarla automáticamente con un archivo de vocabulario personalizado. La inversión en mantener una lista se amortiza rápidamente en ciclos de revisión reducidos y menos quejas de usuarios sobre terminología confusa.
Lo suficientemente larga para cubrir el tema completamente, lo suficientemente corta para mantenerse enfocada. Si una página cubre dos tareas distintas, considera dividirla. Si cubre una tarea pero el contenido es escaso, puede que falten detalles importantes. El contenido de referencia puede ser largo y denso—los usuarios lo escanean. El contenido conceptual debe ser más corto—los usuarios lo leen. Consulta Tipos de contenido para más información sobre cómo ajustar la longitud de la página al propósito del contenido.

Tipos de contenido

Elige el tipo de contenido adecuado para tus objetivos de documentación.

Accesibilidad

Haz que tu documentación sea accesible para más usuarios.

Formato de texto

Aprende las opciones de formato y estilo de texto.

Mejores prácticas de SEO

Mejora la descubribilidad de la documentación.