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

Redator Técnico

Docs como código.

Atualizado: 2026-04-24 14 seções Baixar .zip

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