Paula Silva Software Global Black Belt
LinkedIn
23 enablement · Delivery

Tech WriterRedator TécnicoRedactor Técnico

Docs as code.Docs como código.Docs como código.

2026-04-24 14 sections Download the GitHub Copilot kitBaixar o kit do GitHub CopilotDescargar el kit de GitHub Copilot

The Tech Writer is the persona accountable for documentation that stays current, navigable, and trustworthy. In an AI-native SDLC, the Tech Writer operates a docs-as-code pipeline, not a knowledge-base portal.

Executive summary

The Tech Writer makes the system legible to humans and to AI agents. In an AI-native SDLC, the Tech Writer works inside the Delivery phase with a fixed set of primitives: one docs-curator agent, four slash prompts, scoped instructions, schema-validated hooks, and a curated list of validated MCPs. The primary outputs are MDX and Markdown content in the repository, generated API references, release notes, and a curated table of contents that ships as a static site on Azure Static Web Apps.

Role and responsibilities

Think of the Tech Writer like the map-maker in a growing city. Streets and buildings appear every week; without the map-maker, newcomers are lost and longtimers forget which street is which. In an AI-native SDLC the code and architecture change daily; without the Tech Writer, the map is two quarters stale and the AI agents hallucinate landmarks that no longer exist.

Primary responsibilities:

  • Convert approved specifications into user-facing documentation in MDX or Markdown, committed alongside the code
  • Maintain the table of contents, navigation, and search index of the docs site hosted on Azure Static Web Apps
  • Generate and review release notes for every production deployment
  • Enforce the docs style guide with automated checks in GitHub Actions
  • Partner with developers to keep the CODEMAP.md and the generated API reference in sync
  • Curate content for humans and for AI agents: structured headings, explicit cross-links, predictable metadata
  • Operate the Docs Curator agent and the /spec-to-docs, /style-check, /toc-refresh, /release-note prompts

Jobs to be done

  1. As a Tech Writer, I want an approved specification converted into a draft doc page in minutes, so that I ship docs with features, not after them.
  2. As a Tech Writer, I want the style guide enforced automatically in CI, so that I coach instead of police.
  3. As a Tech Writer, I want the table of contents refreshed whenever a new page lands, so that navigation stays coherent as the site grows.
  4. As a Tech Writer, I want release notes drafted from merged PRs and linked issues, so that every release has a human-readable summary.
  5. As a Tech Writer, I want to detect stale docs automatically when the underlying code changes, so that deprecated guidance disappears before users stumble into it.
  6. As a Tech Writer, I want AI agents to read the docs correctly, so that in-product assistants give users accurate answers.

Pain points before AI-native

  1. Docs land weeks after features. The feature ships, the blog post goes out, and the reference docs appear a month later with outdated screenshots.
  2. Style drift. Every writer has a slightly different voice; the final site reads like a committee.
  3. Broken links are caught by users. Nobody audits navigation; the table of contents references pages that moved or were deleted.
  4. Release notes copy-pasted from commit messages. Users read internal jargon; the note tells them nothing actionable.
  5. Docs invisible to search and AI. Without structured metadata, neither the search engine nor the in-product assistant can find the right page.

AI-native daily workflow

The Tech Writer operates a daily loop. The loop uses GitHub Copilot primitives inside Visual Studio Code, Claude Code at the terminal for long-form drafting, and the Microsoft Learn Docs MCP for grounded references on Microsoft and Azure stacks.

Morning setup

  1. Open Visual Studio Code on the docs repository. GitHub Copilot Chat loads the scoped .github/instructions/docs.instructions.md.
  2. Invoke /toc-refresh. The Docs Curator agent reviews the navigation tree, flags pages added without ToC entries, and proposes reorganizations where sections have grown past the readability threshold.
  3. Read the overnight digest from GitHub Actions: which PRs touched public API surfaces, which release tags were cut, which style checks failed.

Midday execution

  1. Take a specification from the specs/ folder. Invoke /spec-to-docs. The agent produces a draft MDX page with headings, examples, and cross-links to related content. The Tech Writer edits the draft for voice and accuracy.
  2. Run /style-check on changed pages. The agent flags tone drift, passive voice overuse, and terms outside the glossary. The Tech Writer accepts or rejects each suggestion.
  3. Pair with a developer on an ambiguous topic. Use Claude Code at the terminal to drive through the code and summarize behavior, grounded by the Microsoft Learn Docs MCP where the topic touches Azure or Microsoft 365.

Afternoon review

  1. Run /release-note for the upcoming release. The agent ingests merged PRs, linked issues, and incident resolutions, and drafts a human-readable note with sections: new features, fixes, deprecations, breaking changes.
  2. Review PRs that touched docs/ in the main product repo. Ensure every new public surface has a doc page or a link to one.
  3. Close the day by pushing changes. GitHub Actions runs the build, the style check, and the link checker; Azure Static Web Apps publishes the updated site.

Agent

AgentFilePurpose
docs-curator.github/agents/docs-curator.agent.mdDraft docs from specs, enforce style, refresh the ToC, produce release notes

The Docs Curator agent uses claude-sonnet-4-6 by default, with tools read, edit, search, grep, glob, bash. It pulls context from GitHub and Microsoft Learn Docs MCPs. Extended thinking is enabled for long-form style and structure work.

Slash prompts

CommandFilePurpose
/spec-to-docs.github/prompts/spec-to-docs.prompt.mdConvert an approved spec into a draft MDX page
/style-check.github/prompts/style-check.prompt.mdRun the style guide against a changed page
/toc-refresh.github/prompts/toc-refresh.prompt.mdReview and reorganize the table of contents
/release-note.github/prompts/release-note.prompt.mdDraft a release note from merged PRs and linked issues

Instructions scoped

Scoped applyTo keeps docs guidance distinct from code guidance.

Scope (applyTo)FilePurpose
docs/**/*.mdx.github/instructions/docs.instructions.mdVoice, tone, heading discipline, frontmatter schema
docs/release-notes/**.github/instructions/release-notes.instructions.mdRelease-note structure, user-centric phrasing
docs/reference/**.github/instructions/reference.instructions.mdAPI reference conventions, parameter tables, example discipline

Hooks

Hooks are zero-token governance for docs artifacts.

  • pre-commit: reject a page without frontmatter (title, id, updated, summary)
  • post-commit: regenerate the ToC JSON when a new page lands
  • pre-push: run the link checker against changed pages; fail on broken internal links

Validated MCPs

Every MCP below is registered in the MCP catalog. Do not reference any MCP that is not in the catalog.

MCPStatusUse in this persona
Microsoft Learn Docs MCPOfficialGround docs on Microsoft 365, Azure, and GitHub topics in current Microsoft Learn content
GitHub MCP ServerOfficialRead merged PRs, linked issues, and release tags for release-note drafting
Azure MCP ServerOfficial (Microsoft)Inspect Azure Static Web Apps deployment status and Application Insights for docs-site errors
Azure DevOps MCP ServerOfficial (Microsoft)Read work items that drive release notes when the team uses Azure Boards
Playwright MCPOfficial (Microsoft)Drive end-to-end checks on the docs site after deployment (navigation, search, dark mode)
Microsoft 365 Agents SDK MCPOfficial (Microsoft)Announce docs updates and release notes into Microsoft Teams channels

Real examples

Example 1: spec to docs for a new endpoint

Input: An approved specification specs/claims-status.md describes a new endpoint for retrieving claim status.

Invocation: /spec-to-docs specs/claims-status.md.

Expected output:

  1. A draft page docs/reference/claims/status.mdx with frontmatter, a short overview, the request and response schemas, three examples (happy path, not found, forbidden), and cross-links to the authentication page.
  2. A ToC entry proposed in the pre-commit diff; the hook would reject the commit otherwise.
  3. A PR titled docs(claims): add claim status endpoint reference that links back to the spec and the implementation PR.

Example 2: release note for version 2.14.0

Input: Version 2.14.0 merges 23 PRs and closes 11 issues across three product areas.

Invocation: /release-note v2.14.0.

Expected output:

  1. A draft docs/release-notes/2.14.0.mdx with four sections: new features (user-centric phrasing), fixes, deprecations, breaking changes.
  2. Each claim cites a merged PR and a linked issue; internal jargon is rewritten into user vocabulary.
  3. A Teams post via the M365 Agents SDK to the release channel inviting reviewers.
  4. Azure Static Web Apps publishes the note to the preview environment; Playwright MCP runs a navigation smoke test before promotion.

Anti-patterns

  1. Copy-paste release notes from commits. Commit messages are for engineers; release notes are for users. Mitigation: release-notes.instructions.md requires user-centric phrasing and rewrites jargon.
  2. Docs that live outside the repository. A knowledge-base portal detached from code drifts instantly. Mitigation: every page lives in docs/ and ships via GitHub Actions to Azure Static Web Apps.
  3. Screenshots that age silently. Image-based UI docs rot fastest. Mitigation: Playwright MCP regenerates critical screenshots on every docs build.
  4. ToC by hand. A hand-maintained navigation tree goes stale within a sprint. Mitigation: /toc-refresh and the post-commit hook keep the JSON generated.
  5. Style policing in PR reviews. Manual policing frustrates both sides. Mitigation: /style-check runs in CI and comments inline.

KPIs and impact metrics

MetricBaseline (manual)Target (agentic)Measurement
Time from feature merge to docs merge14 daysUnder 24 hoursDocs-merge lag dashboard
Broken link count in productionOver 40ZeroLink checker in GitHub Actions
Style check pass rate on first commit55 percentOver 90 percentCI history
Release-note preparation time6 hoursUnder 45 minutesTime-to-publish log
Docs-site error rate (404 on internal nav)Over 2 percentUnder 0.2 percentApplication Insights
Token efficiencyN/AUnder 150k tokens per weekCopilot usage report

Maturity in four levels

LevelNameMarkers
L1ManualDocs in a separate portal, no style guide, release notes copy-pasted
L2AssistedGitHub Copilot Chat for drafting, docs in repo, ad hoc CI checks
L3AugmentedDocs Curator agent, four slash prompts, scoped instructions, style and link checks in GitHub Actions, site on Azure Static Web Apps
L4AgenticFull primitives kit, hooks enforced, Playwright MCP smoke tests on every deploy, Microsoft Learn Docs MCP grounding on Azure topics, maturity scorecard above 80 percent

Integration with other personas

  • With Requirements Engineer: specifications feed /spec-to-docs
  • With Developer: public API changes trigger docs updates
  • With Release Manager: release tags drive release-note generation
  • With DevRel: tutorials and demos cross-link to the reference docs
  • With UX Designer: screenshots and flow diagrams coordinated
  • With InfoSec Officer: security advisories published with the same pipeline
  • With Product Owner: user-centric phrasing reviewed before release

Glossary

  • Docs as code: the practice of treating documentation sources as code, stored in the repository, reviewed in PRs, built by CI.
  • Frontmatter: the YAML block at the top of an MDX or Markdown file that carries metadata used by the site generator and by AI agents.
  • ToC (table of contents): the generated navigation tree that orders pages for readers and for search.
  • Release note: a user-facing summary of what changed in a release, written in product-user vocabulary.
  • Style check: an automated linter that enforces the docs style guide.
  • Link checker: an automated job that verifies every internal and external link resolves.

References

O Tech Writer é a persona responsável pela documentação que se mantém atualizada, navegável e confiável. Em um SDLC AI-nativo, o Tech Writer opera um pipeline de docs-as-code, não um portal de base de conhecimento.

Resumo executivo

O Tech Writer torna o sistema legível para humanos e para agentes de IA. Em um SDLC AI-nativo, o Tech Writer trabalha dentro da fase de Entrega com um conjunto fixo de primitivas: um agente Docs Curator, quatro slash prompts, instruções com escopo, hooks validados por schema e uma lista curada de MCPs validados. As saídas primárias são conteúdo MDX e Markdown no repositório, referências de API geradas, release notes e um sumário curado que é publicado como um site estático no Azure Static Web Apps.

Papel e responsabilidades

Pense no Tech Writer como o cartógrafo de uma cidade em crescimento. Ruas e edifícios aparecem toda semana; sem o cartógrafo, recém-chegados ficam perdidos e veteranos esquecem qual rua é qual. Em um SDLC AI-nativo, o código e a arquitetura mudam diariamente; sem o Tech Writer, o mapa está dois trimestres defasado e os agentes de IA alucinam pontos de referência que não existem mais.

Responsabilidades primárias:

  • Converter especificações aprovadas em documentação voltada ao usuário em MDX ou Markdown, commitada junto com o código
  • Manter o sumário, a navegação e o índice de busca do site de docs hospedado no Azure Static Web Apps
  • Gerar e revisar release notes para cada deploy em produção
  • Enforçar o guia de estilo de docs com verificações automatizadas no GitHub Actions
  • Parceria com developers para manter o CODEMAP.md e a referência de API gerada em sincronia
  • Curar conteúdo para humanos e para agentes de IA: headings estruturados, cross-links explícitos, metadados previsíveis
  • Operar o agente Docs Curator e os prompts /spec-to-docs, /style-check, /toc-refresh, /release-note

Jobs to be done

  1. Como Tech Writer, eu quero uma especificação aprovada convertida em uma página de doc rascunho em minutos, para que eu entregue docs junto com features, não depois delas.
  2. Como Tech Writer, eu quero o guia de estilo enforçado automaticamente no CI, para que eu mentore em vez de policiar.
  3. Como Tech Writer, eu quero o sumário atualizado sempre que uma nova página aterrissar, para que a navegação continue coerente à medida que o site cresce.
  4. Como Tech Writer, eu quero release notes redigidas a partir de PRs merged e issues linkadas, para que cada release tenha um resumo legível por humanos.
  5. Como Tech Writer, eu quero detectar docs obsoletos automaticamente quando o código subjacente muda, para que orientação deprecada desapareça antes que usuários tropecem nela.
  6. Como Tech Writer, eu quero que agentes de IA leiam os docs corretamente, para que assistentes dentro do produto deem aos usuários respostas precisas.

Dores antes do AI-nativo

  1. Docs aterrissam semanas após features. A feature é entregue, o blog post sai, e os docs de referência aparecem um mês depois com screenshots desatualizados.
  2. Drift de estilo. Cada redator tem uma voz ligeiramente diferente; o site final lê como um comitê.
  3. Links quebrados são descobertos por usuários. Ninguém audita a navegação; o sumário referencia páginas que foram movidas ou deletadas.
  4. Release notes copiadas de mensagens de commit. Usuários leem jargão interno; a note não diz nada acionável.
  5. Docs invisíveis para busca e IA. Sem metadados estruturados, nem o motor de busca nem o assistente dentro do produto conseguem encontrar a página certa.

Fluxo diário AI-nativo

O Tech Writer opera um loop diário. O loop usa primitivas do GitHub Copilot dentro do Visual Studio Code, Claude Code no terminal para redação de longa duração e o Microsoft Learn Docs MCP para referências fundamentadas em stacks Microsoft e Azure.

Setup da manhã

  1. Abra o Visual Studio Code no repositório docs. GitHub Copilot Chat carrega as instruções com escopo .github/instructions/docs.instructions.md.
  2. Invoque /toc-refresh. O agente Docs Curator revisa a árvore de navegação, sinaliza páginas adicionadas sem entradas no sumário e propõe reorganizações onde seções cresceram além do limiar de legibilidade.
  3. Leia o resumo noturno do GitHub Actions: quais PRs tocaram superfícies de API pública, quais tags de release foram cortadas, quais verificações de estilo falharam.

Execução no meio do dia

  1. Pegue uma especificação da pasta specs/. Invoque /spec-to-docs. O agente produz uma página MDX rascunho com headings, exemplos e cross-links para conteúdo relacionado. O Tech Writer edita o rascunho para voz e precisão.
  2. Rode /style-check nas páginas alteradas. O agente sinaliza drift de tom, uso excessivo de voz passiva e termos fora do glossário. O Tech Writer aceita ou rejeita cada sugestão.
  3. Pareie com um developer em um tópico ambíguo. Use Claude Code no terminal para navegar pelo código e resumir comportamento, fundamentado pelo Microsoft Learn Docs MCP quando o tópico toca Azure ou Microsoft 365.

Revisão no fim da tarde

  1. Rode /release-note para o release futuro. O agente ingere PRs merged, issues linkadas e resoluções de incidentes, e redige uma note legível por humanos com seções: novas features, correções, deprecações, breaking changes.
  2. Revise PRs que tocaram docs/ no repo principal do produto. Garanta que toda nova superfície pública tem uma página de doc ou um link para uma.
  3. Feche o dia dando push nas mudanças. GitHub Actions roda o build, a verificação de estilo e o link checker; Azure Static Web Apps publica o site atualizado.

Primitivas recomendadas

Agente

AgenteArquivoPropósito
docs-curator.github/agents/docs-curator.agent.mdRedigir docs a partir de specs, enforçar estilo, atualizar o sumário, produzir release notes

O agente Docs Curator usa claude-sonnet-4-6 por padrão, com ferramentas read, edit, search, grep, glob, bash. Puxa contexto dos MCPs GitHub e Microsoft Learn Docs. Extended thinking é habilitado para trabalho de estilo e estrutura de longa duração.

Slash prompts

ComandoArquivoPropósito
/spec-to-docs.github/prompts/spec-to-docs.prompt.mdConverter uma spec aprovada em uma página MDX rascunho
/style-check.github/prompts/style-check.prompt.mdRodar o guia de estilo contra uma página alterada
/toc-refresh.github/prompts/toc-refresh.prompt.mdRevisar e reorganizar o sumário
/release-note.github/prompts/release-note.prompt.mdRedigir uma release note a partir de PRs merged e issues linkadas

Instruções com escopo

applyTo com escopo mantém a orientação de docs distinta da orientação de código.

Escopo (applyTo)ArquivoPropósito
docs/**/*.mdx.github/instructions/docs.instructions.mdVoz, tom, disciplina de headings, schema de frontmatter
docs/release-notes/**.github/instructions/release-notes.instructions.mdEstrutura de release note, fraseologia centrada no usuário
docs/reference/**.github/instructions/reference.instructions.mdConvenções de referência de API, tabelas de parâmetros, disciplina de exemplos

Hooks

Hooks são governança de zero tokens para artefatos de docs.

  • pre-commit: rejeitar uma página sem frontmatter (title, id, updated, summary)
  • post-commit: regenerar o JSON do sumário quando uma nova página aterrissa
  • pre-push: rodar o link checker contra páginas alteradas; falhar em links internos quebrados

MCPs validados

Todo MCP abaixo está registrado no catálogo de MCPs. Não referencie nenhum MCP que não esteja no catálogo.

MCPStatusUso nesta persona
Microsoft Learn Docs MCPOficialFundamentar docs sobre Microsoft 365, Azure e GitHub em conteúdo atual do Microsoft Learn
GitHub MCP ServerOficialLer PRs merged, issues linkadas e tags de release para redação de release notes
Azure MCP ServerOficial (Microsoft)Inspecionar status de deploy do Azure Static Web Apps e Application Insights para erros do site de docs
Azure DevOps MCP ServerOficial (Microsoft)Ler work items que direcionam release notes quando o time usa Azure Boards
Playwright MCPOficial (Microsoft)Conduzir verificações ponta a ponta no site de docs após deploy (navegação, busca, dark mode)
Microsoft 365 Agents SDK MCPOficial (Microsoft)Anunciar atualizações de docs e release notes em canais do Microsoft Teams

Exemplos reais

Exemplo 1: da spec para docs para um novo endpoint

Entrada: Uma especificação aprovada specs/claims-status.md descreve um novo endpoint para recuperar status de sinistro.

Invocação: /spec-to-docs specs/claims-status.md.

Saída esperada:

  1. Uma página rascunho docs/reference/claims/status.mdx com frontmatter, um overview curto, schemas de request e response, três exemplos (caminho feliz, não encontrado, proibido) e cross-links para a página de autenticação.
  2. Uma entrada de sumário proposta no diff do pre-commit; o hook rejeitaria o commit de outra forma.
  3. Um PR intitulado docs(claims): add claim status endpoint reference que linka de volta à spec e ao PR de implementação.

Exemplo 2: release note para a versão 2.14.0

Entrada: A versão 2.14.0 faz merge de 23 PRs e fecha 11 issues em três áreas de produto.

Invocação: /release-note v2.14.0.

Saída esperada:

  1. Um rascunho docs/release-notes/2.14.0.mdx com quatro seções: novas features (fraseologia centrada no usuário), correções, deprecações, breaking changes.
  2. Cada item cita um PR merged e uma issue linkada; jargão interno é reescrito em vocabulário de usuário do produto.
  3. Um post no Teams via o M365 Agents SDK para o canal de release convidando revisores.
  4. Azure Static Web Apps publica a note no ambiente de preview; Playwright MCP roda um smoke test de navegação antes da promoção.

Anti-padrões

  1. Release notes copiadas de commits. Mensagens de commit são para engenheiros; release notes são para usuários. Mitigação: release-notes.instructions.md exige fraseologia centrada no usuário e reescreve jargão.
  2. Docs que vivem fora do repositório. Um portal de base de conhecimento desacoplado do código se defasa instantaneamente. Mitigação: cada página vive em docs/ e é entregue via GitHub Actions para Azure Static Web Apps.
  3. Screenshots que envelhecem silenciosamente. Docs baseados em imagens de UI apodrecem mais rápido. Mitigação: Playwright MCP regenera screenshots críticos a cada build de docs.
  4. Sumário manual. Uma árvore de navegação mantida à mão fica defasada em uma sprint. Mitigação: /toc-refresh e o hook post-commit mantêm o JSON gerado.
  5. Policiamento de estilo em revisões de PR. Policiamento manual frustra ambos os lados. Mitigação: /style-check roda no CI e comenta inline.

KPIs e métricas de impacto

MétricaLinha base (manual)Meta (agêntico)Medição
Tempo do merge de feature ao merge de docs14 diasMenos de 24 horasDashboard de defasagem de merge de docs
Contagem de links quebrados em produçãoMais de 40ZeroLink checker no GitHub Actions
Taxa de aprovação de style check no primeiro commit55 por centoMais de 90 por centoHistórico de CI
Tempo de preparação de release notes6 horasMenos de 45 minutosLog de tempo-para-publicação
Taxa de erro do site de docs (404 em nav interna)Mais de 2 por centoMenos de 0,2 por centoApplication Insights
Eficiência de tokensN/AMenos de 150k tokens por semanaRelatório de uso do Copilot

Maturidade em quatro níveis

NívelNomeMarcadores
L1ManualDocs em um portal separado, sem guia de estilo, release notes copiadas
L2AssistidoGitHub Copilot Chat para redação, docs no repo, verificações de CI ad hoc
L3AumentadoAgente Docs Curator, quatro slash prompts, instruções com escopo, verificações de estilo e links no GitHub Actions, site no Azure Static Web Apps
L4AgênticoKit completo de primitivas, hooks enforçados, smoke tests do Playwright MCP a cada deploy, fundamentação do Microsoft Learn Docs MCP em tópicos Azure, scorecard de maturidade acima de 80 por cento

Integração com outras personas

  • Com o Requirements Engineer: especificações alimentam /spec-to-docs
  • Com o Developer: mudanças de API pública disparam atualizações de docs
  • Com o Release Manager: tags de release direcionam geração de release notes
  • Com o DevRel: tutoriais e demos fazem cross-link para os docs de referência
  • Com o UX Designer: screenshots e diagramas de fluxo coordenados
  • Com o InfoSec Officer: advisories de segurança publicados com o mesmo pipeline
  • Com o Product Owner: fraseologia centrada no usuário revisada antes do release

Glossário

  • Docs as code: a prática de tratar fontes de documentação como código, armazenadas no repositório, revisadas em PRs, construídas pelo CI.
  • Frontmatter: o bloco YAML no topo de um arquivo MDX ou Markdown que carrega metadados usados pelo gerador de site e por agentes de IA.
  • Sumário (ToC): a árvore de navegação gerada que ordena páginas para leitores e para busca.
  • Release note: um resumo voltado ao usuário do que mudou em um release, escrito em vocabulário de produto-usuário.
  • Style check: um linter automatizado que enforça o guia de estilo de docs.
  • Link checker: um job automatizado que verifica se cada link interno e externo resolve.

Referências

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

Paula Silva | Software Global Black Belt

Start with the platform, not the agents. Comece pela plataforma, não pelos agentes. Comience por la plataforma, no por los agentes.

Building the future of software development with AI and Agentic DevOps.

Knowledge Hub · v3.4.0 · 2026-06-17
Back to the hubVoltar ao hubVolver al hubKnowledge HubKnowledge HubKnowledge Hub
ConnectConectarConectarin/paulanunes
paulasilva · 2026-06-17 EN · PT-BR · ES