De escribir docs a dirigir a los agentes que los escriben

Al final de una entrevista técnica que hice hace poco, la candidata me contó que casi deja por fuera su trabajo con IA. Temía que muchos escritores técnicos (technical writers) todavía se resistan, así que pensaba mostrar solo el lado “clásico” del oficio. Ese momento es la razón de este texto: el lado clásico es justo el que se está yendo.

La versión corta

Creo que en un par de años la mayoría de empresas no va a contratar a alguien solo para escribir documentación. La IA ya lo hace. Con acceso al código, redacta los docs en el momento en que sale un cambio o una versión. El trabajo del escritor técnico se mueve hacia dos cosas: revisar lo que produce la IA y diseñar la experiencia real de quien lee. La gramática deja de ser el cuello de botella; ahí la IA suele hacerlo bien.

No es una mala noticia. Es un ascenso, si lo tomas.

De escritor a director

El rol pasa de escribir documentación a gestionar a los agentes que la escriben. En la práctica, tu guía de estilo deja de ser un PDF que nadie abre. Se vuelve el marco que le das al modelo: qué decir, cómo decirlo, qué palabras usar y cuáles nunca.

Las herramientas ya existen. Las skills de Claude, las Gems de Gemini y los archivos de instrucciones como CLAUDE.md te permiten enseñarle a un agente tu voz, tus plantillas y tus reglas una sola vez, y reutilizarlas en cada página. Construí una de estas para la documentación de Priority Commerce: una skill de Claude que carga el paquete de referencia de cada producto antes de escribir una línea. Lo valioso de verdad: las reglas por fin vivían en un lugar donde una máquina podía seguirlas.

Lo que la máquina todavía hace mal

La IA facilita las cosas. También facilita cometer un error grande si no prestas atención. Un párrafo seguro de sí mismo sobre un endpoint que no existe se lee igual de bien que uno correcto.

Ahí entramos nosotros:

• Exactitud. Alguien tiene que contrastar el resultado con el producto, no con lo creíble que suena.
• Contexto. No sacas todos los matices de un producto de los tickets de Jira y unas cuantas dailies. Saber para qué sirve una función y a quién se le complica sigue siendo trabajo humano.
• Consistencia. Nunca había sido tan fácil mantener la documentación consistente, y aun así los equipos se saltan la revisión. Una guía de estilo solo funciona si alguien la hace cumplir.
• Quien lee. La navegación, los ejemplos, el orden en que aparecen las cosas, el momento en que alguien se rinde: eso es diseño de experiencia, y es nuestro.

Usa la IA también como revisora par. No tiene que cambiar nada. Solo te avisa lo que podrías corregir, y tú decides.

Cinco formas de prepararte

1. Aprende a escribir para agentes. Convierte tu guía de estilo en instrucciones que un modelo pueda seguir: una skill, una Gem, un archivo de instrucciones. Si puedes explicarle tus estándares a alguien nuevo en el equipo, puedes explicárselos a un agente.
2. Entra temprano al ciclo de vida. La documentación no llega después del producto. En la planeación, los requisitos y el diseño es donde detectas los vacíos, y donde un agente más necesita tu contexto.
3. Automatiza lo aburrido. Los equipos de ingeniería están ocupados corrigiendo errores y sacando la siguiente función. Si montas un flujo que lleve la especificación OpenAPI del repositorio a ReadMe, Mintlify o GitBook, y mantenga los endpoints etiquetados y ordenados, les acabas de ahorrar un sprint. No necesitas ser desarrollador. Necesitas unas cuantas automatizaciones sencillas.
4. Revisa como editor, no como corrector. Deja de cazar comas. Caza datos equivocados, pasos que faltan y páginas que responden algo que nadie preguntó.
5. Toma la iniciativa. La mayoría de empresas no sabe lo que puede hacer un escritor técnico. A veces ni siquiera saben qué necesitan. Tus primeras semanas definen cómo te ven, así que propón: investiga qué podrían implementar y llévaselo antes de que te lo pidan.

Por qué importa adaptarse

Si solo te sientes cómodo escribiendo documentación y notas de versión, este cambio te va a golpear fuerte. No te lo voy a endulzar.

Pero si aprendes a dirigir las herramientas, te vuelves la persona que sube el nivel de la documentación y de toda la experiencia a su alrededor. No alguien que marca casillas, sino alguien que hace que el producto sea más fácil de entender, integrar y mantener. Es un mejor trabajo que el que estamos dejando atrás.

Y tranqui: si ya sabes pensar en quien lee, en la estructura y en la claridad, tienes la parte difícil. Las herramientas son la parte fácil. Empieza con una: elige una página, escribe las instrucciones que le darías a un colega nuevo y deja que un agente lo intente. Después revísala como si fuera tuya, porque lo es.