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:

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”

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

Ao adicionar o HTML sugerido, ocorreu um 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.

Agora é copiar a resposta e adicionar ao nosso markdown.

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”

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

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

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

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

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.

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”

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

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?