Cómo escribir documentación técnica

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.

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

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.

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.

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.

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.

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.

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.

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

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.

Incluso unos pocos errores reducen la credibilidad. Indican que nadie revisó el contenido con cuidado, lo que hace que los usuarios se pregunten si el contenido técnico es igualmente poco confiable.

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 detectar problemas de estilo 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.