paulasilvatech ASP Personas del SDLC Agéntico v1.0.0
EN PT ES
23 enablement · Delivery

Redactor Técnico

Docs como código.

Actualizado: 2026-04-24 14 secciones Descargar .zip

El Tech Writer es la persona responsable de que la documentación se mantenga actual, navegable y confiable. En un SDLC AI-nativo, el Tech Writer opera una pipeline de docs-as-code, no un portal de knowledge base.

Resumen ejecutivo

El Tech Writer hace que el sistema sea legible para humanos y para agentes de IA. En un SDLC AI-nativo, el Tech Writer trabaja dentro de la fase de Delivery con un conjunto fijo de primitivas: un agente docs-curator, cuatro slash prompts, instrucciones con alcance, hooks validados por schema y una lista curada de MCPs validados. Las salidas primarias son contenido MDX y Markdown en el repositorio, referencias de API generadas, release notes y una tabla de contenidos curada que se publica como sitio estático en Azure Static Web Apps.

Rol y responsabilidades

Piensa en el Tech Writer como el cartógrafo de una ciudad en crecimiento. Cada semana aparecen calles y edificios; sin el cartógrafo, los recién llegados se pierden y los veteranos olvidan qué calle es cuál. En un SDLC AI-nativo, el código y la arquitectura cambian a diario; sin el Tech Writer, el mapa lleva dos trimestres desactualizado y los agentes de IA alucinan referencias que ya no existen.

Responsabilidades primarias:

  • Convertir especificaciones aprobadas en documentación user-facing en MDX o Markdown, commiteada junto al código
  • Mantener la tabla de contenidos, la navegación y el índice de búsqueda del sitio de docs hospedado en Azure Static Web Apps
  • Generar y revisar release notes para cada despliegue a producción
  • Enforzar la guía de estilo de docs con chequeos automatizados en GitHub Actions
  • Colaborar con los developers para mantener CODEMAP.md y la referencia de API generada en sincronía
  • Curar contenido para humanos y para agentes de IA: encabezados estructurados, cross-links explícitos, metadata predecible
  • Operar el agente Docs Curator y los prompts /spec-to-docs, /style-check, /toc-refresh, /release-note

Jobs to be done

  1. Como Tech Writer, quiero una especificación aprobada convertida en una página draft en minutos, para entregar docs con las features, no después.
  2. Como Tech Writer, quiero la guía de estilo enforzada automáticamente en CI, para coachear en lugar de patrullar.
  3. Como Tech Writer, quiero la tabla de contenidos refrescada cada vez que cae una página nueva, para que la navegación se mantenga coherente mientras el sitio crece.
  4. Como Tech Writer, quiero release notes redactadas a partir de PRs mergeados e issues enlazados, para que cada release tenga un resumen legible para humanos.
  5. Como Tech Writer, quiero detectar docs obsoletas automáticamente cuando cambia el código subyacente, para que la guía deprecada desaparezca antes de que los usuarios tropiecen con ella.
  6. Como Tech Writer, quiero que los agentes de IA lean las docs correctamente, para que los asistentes in-product den respuestas precisas a los usuarios.

Dolores antes del AI-nativo

  1. Las docs caen semanas después de las features. La feature se publica, sale el blog post y los docs de referencia aparecen un mes más tarde con screenshots desactualizados.
  2. Drift de estilo. Cada writer tiene una voz ligeramente distinta; el sitio final se lee como un comité.
  3. Los enlaces rotos los detectan los usuarios. Nadie audita la navegación; la tabla de contenidos referencia páginas que se movieron o eliminaron.
  4. Release notes copiados de mensajes de commit. Los usuarios leen jerga interna; la nota no les dice nada accionable.
  5. Docs invisibles para búsqueda y para IA. Sin metadata estructurada, ni el motor de búsqueda ni el asistente in-product encuentran la página correcta.

Flujo diario AI-nativo

El Tech Writer opera un loop diario. El loop usa primitivas de GitHub Copilot dentro de Visual Studio Code, Claude Code en la terminal para redacción de formato largo, y el Microsoft Learn Docs MCP para referencias grounded en stacks de Microsoft y Azure.

Setup matinal

  1. Abre Visual Studio Code en el repositorio docs. GitHub Copilot Chat carga .github/instructions/docs.instructions.md con alcance.
  2. Invoca /toc-refresh. El agente Docs Curator revisa el árbol de navegación, marca páginas agregadas sin entradas en la ToC y propone reorganizaciones donde las secciones crecieron más allá del umbral de legibilidad.
  3. Lee el digest de la madrugada de GitHub Actions: qué PRs tocaron superficies de API pública, qué tags de release se cortaron, qué chequeos de estilo fallaron.

Ejecución al mediodía

  1. Toma una especificación de la carpeta specs/. Invoca /spec-to-docs. El agente produce una página draft MDX con encabezados, ejemplos y cross-links a contenido relacionado. El Tech Writer edita el draft por voz y precisión.
  2. Ejecuta /style-check sobre las páginas modificadas. El agente marca drift de tono, abuso de voz pasiva y términos fuera del glosario. El Tech Writer acepta o rechaza cada sugerencia.
  3. Empareja con un developer en un tema ambiguo. Usa Claude Code en la terminal para recorrer el código y resumir el comportamiento, grounded por el Microsoft Learn Docs MCP cuando el tema toca Azure o Microsoft 365.

Revisión al final de la tarde

  1. Ejecuta /release-note para el release próximo. El agente ingiere PRs mergeados, issues enlazados y resoluciones de incidentes, y redacta una nota legible para humanos con secciones: nuevas features, fixes, deprecaciones, breaking changes.
  2. Revisa los PRs que tocaron docs/ en el repo principal del producto. Asegúrate de que cada nueva superficie pública tenga una página de docs o un enlace a una.
  3. Cierra el día haciendo push de los cambios. GitHub Actions corre el build, el style check y el link checker; Azure Static Web Apps publica el sitio actualizado.

Primitivas recomendadas

Agente

AgenteArchivoPropósito
docs-curator.github/agents/docs-curator.agent.mdRedactar docs desde specs, enforzar estilo, refrescar la ToC, producir release notes

El agente Docs Curator usa claude-sonnet-4-6 por defecto, con las herramientas read, edit, search, grep, glob, bash. Trae contexto desde GitHub y Microsoft Learn Docs MCP. Extended thinking está habilitado para trabajo de estilo y estructura de formato largo.

Slash prompts

ComandoArchivoPropósito
/spec-to-docs.github/prompts/spec-to-docs.prompt.mdConvertir una spec aprobada en una página draft MDX
/style-check.github/prompts/style-check.prompt.mdEjecutar la guía de estilo contra una página modificada
/toc-refresh.github/prompts/toc-refresh.prompt.mdRevisar y reorganizar la tabla de contenidos
/release-note.github/prompts/release-note.prompt.mdRedactar una release note desde PRs mergeados e issues enlazados

Instrucciones con alcance

applyTo con alcance mantiene la guía de docs distinta de la guía de código.

Alcance (applyTo)ArchivoPropósito
docs/**/*.mdx.github/instructions/docs.instructions.mdVoz, tono, disciplina de encabezados, schema de frontmatter
docs/release-notes/**.github/instructions/release-notes.instructions.mdEstructura de release-note, fraseo centrado en el usuario
docs/reference/**.github/instructions/reference.instructions.mdConvenciones de referencia de API, tablas de parámetros, disciplina de ejemplos

Hooks

Los hooks son gobernanza de cero tokens para artefactos de docs.

  • pre-commit: rechazar una página sin frontmatter (title, id, updated, summary)
  • post-commit: regenerar el JSON de la ToC cuando cae una página nueva
  • pre-push: ejecutar el link checker contra las páginas modificadas; fallar en enlaces internos rotos

MCPs validados

Cada MCP a continuación está registrado en el catálogo de MCPs. No referencies ningún MCP que no esté en el catálogo.

MCPEstadoUso en esta persona
Microsoft Learn Docs MCPOficialGrounding de docs sobre temas de Microsoft 365, Azure y GitHub en contenido vigente de Microsoft Learn
GitHub MCP ServerOficialLeer PRs mergeados, issues enlazados y tags de release para el draft de release notes
Azure MCP ServerOficial (Microsoft)Inspeccionar el estado de despliegue de Azure Static Web Apps y Application Insights para errores del sitio de docs
Azure DevOps MCP ServerOficial (Microsoft)Leer work items que impulsan release notes cuando el equipo usa Azure Boards
Playwright MCPOficial (Microsoft)Ejecutar chequeos end-to-end sobre el sitio de docs después del despliegue (navegación, búsqueda, modo oscuro)
Microsoft 365 Agents SDK MCPOficial (Microsoft)Anunciar actualizaciones de docs y release notes en canales de Microsoft Teams

Ejemplos reales

Ejemplo 1: spec a docs para un nuevo endpoint

Entrada: Una especificación aprobada specs/claims-status.md describe un nuevo endpoint para recuperar el estado de un reclamo.

Invocación: /spec-to-docs specs/claims-status.md.

Salida esperada:

  1. Una página draft docs/reference/claims/status.mdx con frontmatter, una visión general corta, los schemas de request y response, tres ejemplos (camino feliz, no encontrado, prohibido) y cross-links a la página de autenticación.
  2. Una entrada de ToC propuesta en el diff de pre-commit; el hook rechazaría el commit en caso contrario.
  3. Un PR titulado docs(claims): add claim status endpoint reference que enlaza de vuelta a la spec y al PR de implementación.

Ejemplo 2: release note para la versión 2.14.0

Entrada: La versión 2.14.0 mergea 23 PRs y cierra 11 issues a través de tres áreas de producto.

Invocación: /release-note v2.14.0.

Salida esperada:

  1. Un draft docs/release-notes/2.14.0.mdx con cuatro secciones: nuevas features (fraseo centrado en el usuario), fixes, deprecaciones, breaking changes.
  2. Cada afirmación cita un PR mergeado y un issue enlazado; la jerga interna se reescribe al vocabulario del usuario.
  3. Una publicación en Teams vía el M365 Agents SDK al canal de release invitando a los revisores.
  4. Azure Static Web Apps publica la nota al ambiente de preview; el Playwright MCP corre un smoke test de navegación antes de la promoción.

Anti-patrones

  1. Copiar y pegar release notes desde commits. Los mensajes de commit son para ingenieros; las release notes son para usuarios. Mitigación: release-notes.instructions.md requiere fraseo centrado en el usuario y reescribe la jerga.
  2. Docs que viven fuera del repositorio. Un portal de knowledge base separado del código deriva al instante. Mitigación: cada página vive en docs/ y se publica vía GitHub Actions a Azure Static Web Apps.
  3. Screenshots que envejecen en silencio. Las docs de UI basadas en imágenes se pudren más rápido. Mitigación: el Playwright MCP regenera screenshots críticos en cada build de docs.
  4. ToC a mano. Un árbol de navegación mantenido a mano queda obsoleto en un sprint. Mitigación: /toc-refresh y el hook post-commit mantienen el JSON generado.
  5. Patrullaje de estilo en revisiones de PR. El patrullaje manual frustra a ambos lados. Mitigación: /style-check corre en CI y comenta inline.

KPIs y métricas de impacto

MétricaBaseline (manual)Objetivo (agéntico)Medición
Tiempo desde merge de feature hasta merge de docs14 díasMenos de 24 horasDashboard de docs-merge lag
Cantidad de enlaces rotos en producciónMás de 40CeroLink checker en GitHub Actions
Tasa de aprobación del style check en primer commit55 por cientoMás del 90 por cientoHistorial de CI
Tiempo de preparación de release note6 horasMenos de 45 minutosLog de tiempo hasta publicación
Tasa de errores del sitio de docs (404 en navegación interna)Más del 2 por cientoMenos del 0,2 por cientoApplication Insights
Eficiencia de tokensN/AMenos de 150k tokens por semanaReporte de uso de Copilot

Madurez en cuatro niveles

NivelNombreMarcadores
L1ManualDocs en un portal separado, sin guía de estilo, release notes copiadas y pegadas
L2AsistidoGitHub Copilot Chat para redacción, docs en repo, chequeos de CI ad hoc
L3AumentadoAgente Docs Curator, cuatro slash prompts, instrucciones con alcance, chequeos de estilo y enlaces en GitHub Actions, sitio en Azure Static Web Apps
L4AgénticoKit completo de primitivas, hooks enforzados, smoke tests de Playwright MCP en cada despliegue, grounding del Microsoft Learn Docs MCP en temas de Azure, scorecard de madurez por encima del 80 por ciento

Integración con otras personas

  • Con el Requirements Engineer: las especificaciones alimentan /spec-to-docs
  • Con el Developer: los cambios de API pública disparan actualizaciones de docs
  • Con el Release Manager: los tags de release impulsan la generación de release notes
  • Con DevRel: tutoriales y demos hacen cross-link con los docs de referencia
  • Con el UX Designer: screenshots y diagramas de flujo coordinados
  • Con el InfoSec Officer: avisos de seguridad publicados con la misma pipeline
  • Con el Product Owner: fraseo centrado en el usuario revisado antes del release

Glosario

  • Docs as code: la práctica de tratar las fuentes de documentación como código, almacenadas en el repositorio, revisadas en PRs, construidas por CI.
  • Frontmatter: el bloque YAML al inicio de un archivo MDX o Markdown que lleva metadata usada por el generador del sitio y por agentes de IA.
  • ToC (tabla de contenidos): el árbol de navegación generado que ordena las páginas para lectores y para búsqueda.
  • Release note: un resumen user-facing de qué cambió en un release, escrito en vocabulario del usuario del producto.
  • Style check: un linter automatizado que enforza la guía de estilo de docs.
  • Link checker: un job automatizado que verifica que cada enlace interno y externo resuelva.

Referencias