A Inteligência Artificial (IA) está evoluindo rapidamente e transformando a maneira como trabalhamos no mundo da tecnologia, neste artigo vamos tratar especificamente da relação de technical writing com IA.
Segundo o blog da HubSpot, no artigo “How AI Works”, um dos principais benefícios da IA é sua capacidade de realizar tarefas repetitivas, permitindo que as pessoas se concentrem em atividades mais criativas.
Para technical writers, a IA tem o potencial de revolucionar a criação, entrega e gestão da documentação. É necessário nos adaptar e usar ferramentas de IA para aumentar a produtividade, como corrigir erros gramaticais, traduzir conteúdos para diferentes idiomas e revisar textos.
Este artigo mostra como a StackSpot AI é uma ferramenta poderosa com recursos como Quick Commands e Agentes de IA para traduzir e revisar a documentação. Continue lendo para entender mais sobre technical writing com IA.
O que é a StackSpot AI?
A StackSpot AI é um assistente de inteligência artificial projetado para melhorar a qualidade do código e simplificar fluxos de trabalho. Você pode integrar a StackSpot AI à sua conta do GitHub para simplificar processos diários e melhorar a eficiência do seu trabalho.
Para isso, você precisa fazer o download e usar a extensão na sua IDE, como um chat, e acessar o Portal StackSpot AI para outros recursos.
Consulte a documentação para mais informações sobre como baixar a extensão e usar a plataforma.
Usando a StackSpot AI
A StackSpot AI pode ajudar na tradução de idiomas, como do inglês para português, através de um de seus recursos, o Quick Commands.
Quick Commands são instruções predefinidas que podem ser dadas ao modelo de linguagem grande (LLM) para executar ações específicas e fornecer maneiras rápidas e eficientes de dar contexto a LLM. São fáceis de usar e acessíveis simplesmente clicando com o botão direito do mouse ou pela iteração diretamente no chat digitando “/”.
Confira, a seguir, alguns exemplos de uso:
Caso 1: Quick Commands para Traduções
Problema: inicialmente, nossa documentação estava em inglês e precisava ser rapidamente traduzida para português para expandir o uso do nosso produto.
Solução: desenvolvemos um Quick Command IDE e criamos um prompt para traduzir páginas em inglês para português. Aqui está um resumo dos passos que fizemos no Portal da StackSpot AI:
1. Baixar a extensão do marketplace do seu IDE;
2. Acessar a StackSpot AI e fazer login usando sua conta do GitHub. Em seguida, vá para a seção Quick Command para criar um;
3. Selecionar a opção IDE (já que usamos a documentação como código e trabalhamos com o conceito de IDEs/repositório);
4. Fornecer um nome e o comando que aparecerá na sua IDE, e descreva seu propósito;
5. Escolher a opção de prompt e especificar o que você quer que o comando faça;
6. Você pode incorporar Knowledge Sources que são “pedaços de informação” para ajudar a aderir ao tom, voz e estilo do seu texto. Enfim, adicionar mais informações relevantes pode melhorar a experiência de usar a StackSpot AI.
Usando o Comando
Para usar o comando, navegue até seu projeto na IDE, selecione o documento que deseja traduzir e clique com o botão direito ou utilizando o´/´ no chat. Em seguida, escolha StackSpot AI > My Quick Commands > O nome do seu comando.
Resultado
A tradução foi excelente. Foi mais rápida e melhor do que tradutores regulares. O Knowledge Source também nos ajudou a ajustar o tom do texto conforme desejado.
Após executar o comando, ainda foi necessário revisar o conteúdo e ajustar algumas palavras, pois as frases precisavam de um toque mais refinado para melhorar a qualidade e a fluidez. No entanto, esse processo nos permitiu concluir toda a documentação em português em menos tempo do que o esperado.
Confira a nossa documentação da StackSpot AI em português.
Caso 2: Quick Commands para ajudar a revisar a acessibilidade do texto
Garantir que seu conteúdo seja acessível a todas pessoas usuárias é essencial. Tivemos o desafio de melhorar a acessibilidade de nossos documentos, e a StackSpot AI tem sido uma grande aliada nesse processo. Confira os passos do nosso progresso:
- Criamos outro Quick Command IDE, seguindo os mesmos passos mencionados anteriormente.
- O objetivo é ajudar a equipe de documentação a verificar a acessibilidade dos textos, garantindo, por exemplo, que as imagens tenham descrições alternativas adequadas.
- Editamos o prompt várias vezes até alcançar o resultado desejado.
O recurso Knowledge Source foi fundamental, fornecendo informações adicionais sobre as Diretrizes de Acessibilidade para Conteúdo Web (WCAG), o que resultou em respostas mais precisas. Ao usar o comando, a StackSpot AI retornou o resultado no chat da IDE com as seguintes diretrizes:
1. Descrição de Links
Os links devem ter descrições claras e objetivas. Vamos revisar e corrigir os links que não seguem essa regra.
Antes:
Confira como [**criar a Conta Personal**](link).
Confira mais informações sobre a [**Conta Enterprise**](link)
Para saber mais sobre as diferenças entre os tipos de conta, confira a seção sobre [**Contas na StackSpot**](link).
[**Confira os conceitos da StackSpot EDP**](link).
Depois
[**Confira como criar a sua Conta Personal na StackSpot**](link).
[**Confira mais informações sobre a Conta Enterprise da StackSpot**](link).
Para saber mais sobre as diferenças entre os tipos de conta, [**confira a seção sobre tipos de contas na StackSpot**](link).
[**Confira os principais conceitos da StackSpot EDP**](link).
Antes:
**1.** Acesse o [**Portal da StackSpot AI**](link) e no menu principal selecione **Knowledge Sources**;
Depois:
**1.** Acesse o [**Portal da StackSpot AI para criar Knowledge Sources**](link) e no menu principal selecione **Knowledge Sources**;
3. Descrição de Imagens
As imagens devem ter descrições detalhadas e objetivas.
Antes:
alt="Diagrama de hierarquia de conteúdos na StackSpot dentro de Estúdios."
alt="Diagrama de hierarquia entre conteúdos de Estúdios e Workspace."
Depois:
"Diagrama mostrando a hierarquia de conteúdos na StackSpot dentro de Estúdios. O diagrama ilustra a relação entre Stacks, Plugins, Actions e Starters."
"Diagrama mostrando a hierarquia entre conteúdos de Estúdios e Workspace na StackSpot. O diagrama ilustra como os conteúdos dos Estúdios são utilizados nos Workspaces para criar Aplicações e Infraestrutura."
Antes:
alt=Captura de tela da interface da StackSpot, mostrando um modal no centro da tela. O modal está explicando o conceito de 'Knowledge Source' e inclui um botão rotulado 'Criar Knowledge Source'. Ao clicar neste botão, aparecem três opções de criação: API, Custom e Snippets Group
Depois:
alt=Captura de tela da interface da StackSpot, mostrando um modal na tela. O modal está explicando o conceito de Knowledge Source e inclui um botão rotulado Criar Knowledge Source. Ao clicar neste botão, aparecem três opções de criação: API, Custom e Snippets Group. O modal pode ser fechado clicando no botão Fechar ou pressionando a tecla ESC.
5. Outros Ajustes
Vamos revisar outros pontos que podem melhorar a acessibilidade, como a estrutura dos títulos e a formatação de listas.
Antes:
## **Quem pode usar a StackSpot EDP?**
- **Pessoas desenvolvedoras trabalhando individualmente:** A Plataforma EDP oferece a conta **Personal**, que é a conta **individual** da StackSpot.
Ou seja, você é dono da conta e pode utilizar as features disponíveis, mas sem compartilhar conteúdo.
Confira como [**criar a sua Conta Personal**](link).
- **Empresas**: A conta do tipo **Enterprise** oferece soluções para empresas que precisam trabalhar com diversas pessoas e equipes.
Sendo assim, a Empresa é a dona da Conta e pode adicionar membros para utilizar as ferramentas disponíveis com níveis diferentes de permissionamento.
Confira mais informações sobre a [**Conta Enterprise**](link)
Depois:
## **Quem pode usar a StackSpot EDP?**
### **Pessoas desenvolvedoras trabalhando individualmente**
A Plataforma EDP oferece a conta **Personal**, que é a conta **individual** da StackSpot. Ou seja, você é dono da conta e pode utilizar as features disponíveis, mas sem compartilhar conteúdo.
[**Confira como criar a sua Conta Personal na StackSpot**](link).
### **Empresas**
A conta do tipo **Enterprise** oferece soluções para empresas que precisam trabalhar com diversas pessoas e equipes. Sendo assim, a Empresa é a dona da Conta e pode adicionar membros para utilizar as ferramentas disponíveis com níveis diferentes de permissionamento.
[**Confira mais informações sobre a Conta Enterprise da StackSpot**](link).
Conclusão do Quick Command
Essas correções ajudam a tornar o documento mais acessível, seguindo as diretrizes de acessibilidade digital. Certifique-se de revisar todo o documento para garantir que todas as seções estejam em conformidade com as regras de acessibilidade.
Após isso, para melhorar a acessibilidade, estamos aprimorando os textos alternativos para imagens, estruturas de cabeçalhos adequadas e descrições de links. Também estamos melhorando esse comando, o que nos ajudará a entregar uma documentação mais acessível.
Caso 3: Agentes de IA
A StackSpot AI trouxe uma nova funcionalidade, os Agentes especializados. Esses Agentes de IA são completamente personalizáveis e foram projetados para te ajudar em qualquer tipo de tarefa, desde a geração de código, controle de qualidade, até a criação e melhoria de documentações.
Nós, do time de Tech Writing, criamos um Agente de verificação de acessibilidade para nos ajudar a checar se o arquivo é mais acessível do que as versões anteriores. Ele aponta melhorias na qualidade da linguagem que usamos, na estrutura do documento e fornece textos alternativos mais precisos.
Confira os passos de como criamos um Agente:
- Acessar o Portal da StackSpot AI e fazer o login;
- Clicar na seção ‘Agentes’ ;
- Clicar em ‘Criar Agente’ e preencher os campos:
- Nome: Check Accessibility
- Prompt do sistema: aqui é onde escrevemos todas as instruções e informações para que o Agente retorne o que você precisa. Você estabelece o tom e modelo que ele precisa seguir. Confira o exemplo:
Você é um Technical Writer especializado em acessibilidade de conteúdos, com profundo conhecimento das diretrizes WCAG (Web Content Accessibility Guidelines). Sua principal responsabilidade é revisar e garantir que os textos, tanto em português quanto em inglês, estejam em conformidade com as normas de acessibilidade. Para cada texto selecionado, você deve identificar e corrigir problemas de acessibilidade, como contraste de cores, legibilidade, estruturação adequada, uso de linguagem clara e objetiva, e outros aspectos que possam impactar a experiência de leitura de pessoas com deficiência. Seu objetivo é tornar os textos mais inclusivos e acessíveis, seguindo rigorosamente as diretrizes WCAG.- Comandos sugeridos: esse campo são frases ou perguntas preestabelecidas para ajudar a pessoa usuária a interagir com seu Agente.
- Exemplo: Revise este texto e corrija-o com foco em acessibilidade.
- Modo conversacional: Ao selecionar esta opção, você permite que haja inúmeras trocas de mensagens entre a pessoa usuária e o Agente.
- No nosso exemplo, selecionamos essa opção, caso haja necessidade de rever algum ponto, podemos conversar com o Agente.
- Knowledge Sources (KSs): Os KSs fornecem contexto mais especializado e personalizado ao seu contexto. Adicionamos alguns Knowledge Sources de boas práticas de acessibilidade, regras da WCAG, GAIA – Guia de Acessibilidade de Interfaces para Autismo, Horcel.
Conferindo exemplos
O Agente está pronto! Para utilizar é bem simples, você pode testar no próprio Portal da StackSpot AI, copiando o texto e colando na área de Try para ser revisado. Você também pode acessar a IDE onde seu projeto está e selecionar o Agente. Confira alguns exemplos de antes e depois de Technical Writing com IA:
Antes:
- **Nome do Quick Command:** adicione um nome para o seu comando.
> Technical Debt
- **Comando:** adicione um nome que você usará mais tarde; ele deve seguir o padrão de slug. Para mais informações sobre Slugs, [**confira o padrão do slug**](link).
> technical_debt_1
- **Descrição:** adicione uma descrição do que o seu comando pode fazer.
> Criar uma issue no GitHub destacando a dívida técnica no código selecionado e sugerir uma forma de correção.
**Passo 6.** Clique no botão **'Próximo'**. Você pode usar os templates disponíveis (já está pré preenchido) ou criar um do seu jeito, em branco.
Confira um exemplo:
Depois:
- **Nome do Quick Command:** adicione um nome claro e descritivo para o seu comando.
> Exemplo: Technical Debt
- **Comando:** adicione um nome que será usado posteriormente. Ele deve seguir o padrão de slug. Para mais informações sobre Slugs, [**confira o padrão do slug**](link).
> Exemplo: technical_debt_1
- **Descrição:** adicione uma descrição clara e objetiva sobre o que o seu comando faz.
> Exemplo: Criar uma issue no GitHub destacando a dívida técnica no código selecionado e sugerir uma forma de correção.
**Passo 6.** Clique no botão **'Próximo'**. Você pode escolher entre usar os templates disponíveis (pré-preenchidos) ou criar um template do zero, conforme sua necessidade.
Confira um exemplo de criação:
Antes:
Aprenda como criar um Knowledge Source. Siga as instruções:
**1.** Acesse o [**Portal da StackSpot AI**](link) e no menu principal selecione **Knowledge Sources**;
**2.** Clique em **‘Knowledge Sources’**. Em seguida, clique no botão de adição;
**3.** Escolha o tipo de Knowledge Source que deseja criar. Cada tipo possui campos específicos. Selecione um e siga os passos.
Depois:
Siga as instruções abaixo para criar um Knowledge Source na StackSpot AI:
1. Acesse o Portal da StackSpot AI
Clique aqui para acessar o Portal da StackSpot AI.
No menu principal, selecione "Knowledge Sources".
2. Adicionar um Novo Knowledge Source
Clique em "Knowledge Sources" no menu lateral.
Em seguida, clique no botão de adicionar para criar um novo Knowledge Source.
3. Escolha o Tipo de Knowledge Source
Selecione o tipo de Knowledge Source que deseja criar. Cada tipo possui campos específicos.
Siga as instruções na tela para preencher os campos necessários.
Descrição da Imagem:
![Captura de tela da interface da StackSpot, mostrando um modal na tela. O modal explica o conceito de Knowledge Source e inclui um botão rotulado Criar Knowledge Source. Ao clicar neste botão, aparecem três opções de criação: API, Custom e Snippets Group. O modal pode ser fechado clicando no botão Fechar ou pressionando a tecla ESC].Também desenvolvemos um Agente para nos ajudar a corrigir erros e trazer melhorias, essencialmente refinando nosso trabalho e eliminando erros comuns de digitação e gramática. Utilizar Agentes resulta em uma economia significativa de tempo para tarefas que, de outra forma, seriam demoradas.
Consuma inovação, comece a transformação
Assine nosso boletim informativo para se manter atualizado sobre as práticas recomendadas mais recentes para aproveitar a tecnologia para gerar impacto nos negócios
Conclusão
A StackSpot AI é uma ferramenta poderosa para profissionais de technical writing. Ela oferece recursos que simplificam o processo de tradução e garantem que seu conteúdo seja acessível a todas as pessoas.
Além disso, Technical Writing com IA por meio da StackSpot oferece uma gama de funcionalidades que permitem personalizar seu fluxo de trabalho de acordo com suas necessidades.
E o melhor: a StackSpot AI está em constante evolução, com novos recursos sendo adicionados regularmente para tornar sua experiência ainda mais eficiente. Acompanhe as atualizações!
Para mais informações sobre como começar a usar a StackSpot AI, visite a documentação da ferramenta.
Quer colocar em prática o que conferiu no artigo? Entre na StackSpot AI e comece agora mesmo.
Referências
How AI Works: The Basics You Need to Know – Hubspot
