Documentação técnica com IA: potencialize com StackSpot AI

Capa do artigo "Documentação técnica com IA: potencialize com StackSpot AI" com três pessoas asiáticas no escritório. Uma delas está com um caderno nas mãos e a outra com um tablet.
Melhore sua experiência produzindo documentação técnica com IA e Docusaurus sem perder a qualidade e clareza necessárias. Saiba mais no blog.

Antes de falar de documentação técnica com IA, é importante salientar o quanto ela é fundamental para o sucesso em projetos de desenvolvimento de software. A documentação serve como referência para consultas, onboarding de novas pessoas no time, disseminação de conhecimento, entender o “porquê” de decisões estratégicas e muito mais.

Neste artigo, vamos usar uma ferramenta de inteligência artificial generativa, a StackSpot AI, para facilitar a criação e melhorar a qualidade das documentações. Acompanhe!

Ferramentas de documentação técnica

Para criar uma boa documentação, podemos utilizar algumas ferramentas que tornam o processo mais fácil e a leitura mais agradável.

Um exemplo é o GitHub Pages, que é um serviço de hospedagem de sites estáticos oferecido pelo GitHub.

Outra ferramenta é o Docusaurus, que aproveita todo o poder do React para tornar seu site totalmente interativo. Ele foi criado com o objetivo de fornecer funcionalidades voltadas para documentações, mas pode ser usado para criar qualquer tipo de página (website pessoal, produto, blog, páginas de marketing, etc.).

Aliás, a utilização de inteligência artificial (IA) na criação e manutenção de documentações técnicas está se tornando cada vez mais comum, especialmente com plataformas como o Docusaurus. 

A seguir, exploramos os principais benefícios de integrar IA na criação de componentes dentro dessa plataforma.

Componentizando exibição de badges

Desenvolvido pela SonarSource, o SonarQube é uma ferramenta de análise de código que auxilia na detecção de problemas que podem ocorrer no código, sejam eles problemas com code smells, segurança ou bugs.

Ele oferece a visualização de várias métricas através de badges, que são uma forma simples e prática de exibir algum conteúdo. Neste caso, gostaríamos de, dentro da nossa documentação, tornar visíveis os dados do Sonar para aqueles que desejam ler as informações mais técnicas do sistema.

Aqui, mostraremos um exemplo de como a StackSpot AI facilita a criação de um componente para exibição dos badges. Usando uma formatação em markdown fornecida pelo próprio Sonar, temos o seguinte resultado:

Captura de imagem de Badges do Sonar desalinhados.

Essas alterações da documentação técnica com IA visam melhorar a clareza e a fluidez do texto, além de corrigir pequenos erros gramaticais e de formatação.

Agilizando o processo com a StackSpot AI

Depois dos dados disponibilizados, vamos melhorar a sua visualização, exibindo os badges um ao lado do outro. Nesse ponto, aqueles com experiência em páginas web já têm uma ideia do que precisa ser feito, mas o tempo necessário para esse ajuste pode ser considerável. Então, vamos utilizar a StackSpot AI para acelerar esse processo.

Inicialmente, vamos usar o seguinte prompt:

“Como desenvolvedor, estou documentando meu projeto nas páginas do github e docusaurus e gostaria de exibir esses badges lado a lado”

Captura de imagem inserindo prompt solicitando para alinhar os badges lado a lado.

Como resposta, temos um HTML a ser adicionado ao markdown para exibir os badges como pedido.

Resposta ao prompt de alinhamento dos badges lado a lado.

Ao adicionar o HTML sugerido, ocorreu um erro.

Página com mensagem de erro.

Mas basta perguntar à StackSpot AI uma forma de resolvê-lo:

“Com base na resposta anterior, como posso resolver o seguinte erro:

The `style` prop expects a mapping from style properties to values, not a string. For example, style={{marginRight: spacing + 'em'}} when using JSX.”

Como resposta, foi sugerido utilizar o atributo “style” como objeto Javascript dentro do HTML.

Resposta do prompt solicitando ajuda para resolver erro de estilo.

Agora é copiar a resposta e adicionar ao nosso markdown.

Captura de imagem onde copiamos a respostas e adicionamos ao nosso markdown.
Captura de imagem com métricas quality gate passed, security A, vulnerabilities 0 e coverage 17,4%.

Melhorando o resultado com IA

O resultado ficou muito bom, mas podemos melhorar ainda mais a documentação técnica com IA. Vamos transformar esse alinhamento de badges em um componente para ser reutilizado em outras partes do documento.

“Como desenvolvedor, estou documentando meu projeto com github pages e docusaurus e gostaria de transformar esse HTML em um componente, para que ele possa ser reaproveitado em outras partes da minha documentação”

Prompt solicitando como transformar o HTML em um componente reutilizável.

E temos a seguinte instrução para alterar nossa documentação.

Parte 1 de 2 da resposta de como criar componente a partir do HTML.
Parte 2 de 2 da resposta de como criar componente a partir do HTML.

Depois de seguir o primeiro passo, criamos nosso componente React, que espera pelo id do projeto no Sonar para montar o HTML.

Captura de imagem onde criamos nosso componente React e espera o id do projeto no Sonar.

Já o segundo passo foi ajustar o markdown para utilizar o componente criado.

Adaptando markdown para usar o componente.

Pronto! O componente pode ser facilmente reutilizado em outras partes.

Reutilizando componente em outras partes.
Pagina exibindo badges através do componente.

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

Benefícios de utilizar StackSpot AI

A StackSpot AI pode agregar valor às suas ferramentas de documentação, acompanhe os principais benefícios:

  • Automação de tarefas repetitivas: a StackSpot AI pode ajudar a automatizar a criação de componentes padrão, economizando tempo e esforço.
  • Sugestões inteligentes: com base no contexto do seu projeto, a StackSpot AI pode sugerir melhorias e otimizações para seus componentes.
  • Consistência: garantir que todos os componentes sigam um padrão consistente, melhorando a manutenção e a escalabilidade do projeto.

Conheça como é a experiência de tech writers com a StackSpot AI:

Formatação de dados

A partir de agora, vamos pensar em um conjunto de dados a serem exibidos na sua documentação para referência. A StackSpot AI pode ser uma ferramenta poderosa para automatizar a formatação de dados e a criação de tabelas a partir de textos não estruturados. 

A seguir, confira como você pode usar a StackSpot AI para extrair dados de um texto e formatá-los em uma tabela que pode ser inserida em um arquivo markdown no Docusaurus.

No exemplo abaixo, temos um arquivo texto, listando os bairros e seus CEPs. Mas eles não estão em uma estrutura de fácil leitura. Poderíamos gastar tempo buscando alternativas na internet ou, no pior dos casos, alterando manualmente.

Captura de tela com os dados a serem analisados (endereços).

Com um simples prompt, a StackSpot AI fará isso de maneira muito mais rápida.

“Como technical writer, quero transformar esta lista de dados em uma tabela para ser exibida em markdown”

Prompt sollicitando transformar uma lista de dados em tabela markdown.

Como saída, temos os dados prontos para serem copiados para sua documentação e serem apresentados de maneira muito mais agradável.

Resposta do prompt com a lista transformada em tabela markdown.
Adicionando ao markdowm a tabela gerada no prompt.
Página exibindo a tabela de CEP.

Conclusão

A integração da StackSpot AI na criação e manutenção de documentações oferece uma série de benefícios que podem transformar significativamente a forma como gerenciamos e apresentamos informações. 

A automação de tarefas repetitivas, como a formatação de dados, não só economiza tempo e esforço, mas também garante uma consistência e qualidade superiores nos documentos produzidos. 

Além disso, a capacidade de incorporar componentes React diretamente nos arquivos markdown do Docusaurus permite criar documentações mais interativas e dinâmicas, proporcionando uma experiência aprimorada.

Impacto da documentação técnica com IA

Portanto, a StackSpot AI pode automatizar a extração e a formatação de dados, economizando tempo e esforço. Além disso, com base no contexto do seu projeto, pode sugerir melhorias e otimizações na formatação, assegurando a adesão a um padrão consistente e aprimorando a manutenção e a escalabilidade do projeto.

A utilização das ferramentas não apenas facilita o trabalho das pessoas desenvolvedoras e redatoras, mas também assegura que o conteúdo final seja claro, preciso e envolvente.

Em resumo, a StackSpot AI se apresenta como uma ferramenta indispensável para qualquer equipe que busca otimizar seus processos de documentação técnica com IA, garantindo eficiência, qualidade e uma melhor experiência para as pessoas usuárias finais.

E aí? O que está esperando para começar a usar StackSpot AI?

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

Related posts

*Material em Inglês

Baixe grátis o eBook
e descubra caminhos para evoluir sua empresa