Blog

Programação por Voz: Escrever Documentação e Comentários Falando

O Mito da Programação por Voz

Quando desenvolvedores ouvem "programação por voz," a maioria imagina alguém ditando sintaxe Python em voz alta: "def espaço calcular sublinhado total abrir parêntese items fechar parêntese dois pontos..." Isso não é programação por voz. Isso é tortura.

Programação por voz real não é sobre substituir entrada de teclado para sintaxe. É sobre usar sua voz para a grande porção do desenvolvimento de software que é linguagem natural: documentação, comentários, mensagens de commit, descrições de PR, breakdowns de tarefas, atualizações de Slack, e revisões de código.

A razão de linguagem natural para sintaxe na maioria do trabalho de desenvolvimento é mais alto do que a maioria dos desenvolvedores percebe. Um desenvolvedor cuidadoso pode passar:

  • 20% escrevendo código
  • 30% escrevendo documentação e comentários
  • 15% escrevendo descrições de issue e conteúdo de PR
  • 20% em Slack, email, e reuniões
  • 15% em revisão de código e planejamento

Isso é 80% do trabalho onde entrada de voz é mais rápida do que digitar ou igualmente efetiva. Os 20% que é sintaxe real fica no teclado.

O Que Ditar Como um Desenvolvedor

Comentários de Código

Comentários são linguagem natural pura. Escrever um comentário claro explicando por que uma função existe, quais casos extremos ela lida, ou o que o chamador deve saber é mais fácil falar do que digitar.

O fluxo de trabalho: Navegue para o local do comentário no seu editor, pressione o atalho, fale a explicação, solte. O modo Clean remove preenchimentos e produz prosa limpa.

Exemplo: Pressione atalho, fale "essa função lida com o caso extremo onde o token do usuário expirou mas o token de atualização ainda é válido, tenta uma atualização e então força um logout se aquilo também falhar, o chamador deve lidar com o AuthenticationError," solte. O comentário aparece formatado e limpo.

Documentação e README

Arquivos README, documentação de API, e comentários JSDoc/docstring inline são exatamente onde entrada de voz se destaca. Você está escrevendo para um leitor humano em prosa natural — a mesma coisa que você diria se alguém o pedisse para explicar o código.

Falar documentação de uma função enquanto olha para o código produz documentação melhor do que digitá-la. Você descreve o que vê naturalmente, sem a fricção de traduzir pensamento para toques de teclado.

Mensagens de Commit

Mensagens de commit boas são prosa curta: o que mudou e por quê. Falar uma mensagem de commit é mais rápido do que digitá-la, e o modo Clean garante que leia bem.

Descrições de Pull Request

Descrições de PR — problema, solução, plano de teste, notas de revisor — são exatamente o tipo de conteúdo estruturado que os modos de enriquecimento de Telvr lidam bem. O modo Dev Task produz essa estrutura nativamente.

Exemplo: Pressione atalho, mude para modo Dev Task, fale "corrigida a race condition no fluxo de processamento de pagamento, o problema era duas requisições concorrentes poderiam ambas verificar o saldo antes de qualquer uma deduzi-lo, adicionei um row lock de nível de banco de dados em volta da transação, adicionei um teste que cria duas tentativas de pagamento concorrentes," solte. O resultado é uma descrição de PR estruturada com problema, solução, e notas de teste.

Descrições de Issue e Ticket

Escrever um relatório de bug detalhado ou especificação de feature digitando é tedioso. Falá-lo naturalmente enquanto olha para o issue é mais rápido e frequentemente produz descrições mais thorough porque você não está lutando com a carga mecânica de digitação.

Atualizações Slack e de Time

Atualizações de progresso, bloqueadores, resumos de standup — esses são conversacionais por natureza. "Terminei o refactor de auth ontem, hoje estou trabalhando na integração de pagamento, bloqueado em obter credenciais de teste do ambiente sandbox, vou perguntar à Sarah." Isso é um standup completo em 15 segundos de fala.

Configurando para Fluxos de Trabalho de Desenvolvedor

Configuração de Atalho

O atalho padrão de Telvr (Option + Space no Mac) funciona bem para desenvolvedores porque não conflita com a maioria dos atalhos de IDE. Se você preferir algo diferente, o atalho é configurável.

Configuração recomendada para desenvolvedores:

  • Mantenha as mãos na linha inicial
  • Use uma combinação de duas teclas para prevenir ativação acidental enquanto no terminal
  • Evite atalhos que conflitem com seu IDE (verifique mapa de teclado VS Code ou JetBrains)

Seleção de Modo

Para fluxos de trabalho de desenvolvedor:

  • Modo Clean: Comentários gerais, documentação em prosa, mensagens Slack
  • Modo Dev Task: Descrições de PR, especificações de issue, resumos de requisito técnico
  • Modo Meeting Notes: Notas retrospectivas pós-sprint, resumos de discussão de design
  • Modo Email: Comunicação técnica para cliente, atualizações de status para stakeholders não-técnicos

Integração de IDE

Telvr usa inserção de texto em todo o sistema, o que significa que funciona em qualquer campo de texto em qualquer aplicação. Isso inclui:

  • VS Code (editor de código, terminal integrado, busca, comentários)
  • JetBrains IDEs (IntelliJ, WebStorm, PyCharm)
  • Zed, Neovim (quando em modo insert)
  • Linear, Jira, GitHub (em navegador)
  • Terminal (quando entrando texto não-comando como mensagens de commit git)

Não há plugin para instalar. Qualquer campo de texto editável é jogo justo.

Fluxo de Trabalho Real de Desenvolvedor

Aqui está como uma sessão de desenvolvimento com entrada de voz parece na prática:

Standup matinal em Slack: Pressione atalho, fale progresso de ontem + plano de hoje + bloqueadores, solte. Feito em 20 segundos.

Escrevendo código: Teclado. Fluxo de trabalho de desenvolvimento normal.

Adicionando um comentário a uma função complexa: Navegue para a linha certa, pressione atalho, fale explicação naturalmente, solte.

Criando um GitHub issue para um bug: Abra novo issue, pressione atalho com modo Dev Task, descreva o bug e passos de reprodução, solte. Titule o issue, submeta.

Escrevendo uma mensagem de commit: git commit no terminal, pressione atalho no editor que abre (ou pipe para arquivo), fale a descrição de commit, solte.

Escrevendo uma descrição de PR: Abra formulário de PR, pressione atalho com modo Dev Task, explique o que o PR faz e por quê, solte. Adicione notas de revisor se necessário.

Respondendo uma pergunta técnica em Slack: Pressione atalho, explique a decisão técnica ou conceito em voz alta, solte. Modo Clean produz uma explicação legível sem ter que digitar com cuidado.

A Realidade de Produtividade

Os maiores ganhos de entrada de voz em desenvolvimento não vêm de puro speed, mas de redução de fricção. Documentação é frequentemente adiada ou pulada inteiramente porque digitar parece como overhead em cima do trabalho real de codificação. Quando escrever um comentário ou docstring leva 15 segundos de fala em vez de 2 minutos de digitação cuidadosa, o limiar para adicioná-lo diminui significativamente.

Código melhor documentado, descrições de PR mais completas, e relatórios de issue mais thorough são frequentemente o resultado prático de entrada de voz de desenvolvedor — não apenas execução mais rápida dos mesmos hábitos.

Uma Semana para um Novo Hábito

Colocando entrada de voz no seu fluxo de trabalho de desenvolvimento:

Dia 1: Use voz apenas para mensagens Slack. Nada mais.

Dia 3: Adicione mensagens de commit. Fale a descrição no editor de terminal.

Dia 5: Adicione comentários inline. Comece a narrar funções complexas enquanto as termina de escrever.

Dia 7: Adicione descrições de PR com modo Dev Task. Repare que você escreve descrições mais completas do que antes porque falar é mais rápido do que digitar.

Após duas semanas, os hábitos são estabelecidos e entrada de voz se sente natural em vez de esforçado.