A documentação técnica, seja interna ou externa para pessoas usuárias finais, é uma grande aliada no desenvolvimento de funcionalidades e produtos, por ajudar a manter o histórico e auxiliar na capacitação de pessoas em relação às tecnologias de uma companhia, time ou projeto.
O processo para criar documentações leva tempo, pois conta com etapas que demandam trabalho manual e carga cognitiva, um esforço pode se tornar facilmente um “gargalo” para que pessoas desenvolvedoras e Technical Writers (TWs) produzam e publiquem novos conteúdos.
Ao entender esse problema, é preciso pensar em formas de otimizar as etapas da documentação técnica para quem produz e contribui com esse processo. O objetivo é alimentar um processo eficiente que evolua o fluxo de trabalho para equipes de agentes de transformação ao invés de agentes de execução.
A cultura de documentação em times de desenvolvimento
Construir uma cultura de documentação é uma tarefa desafiadora e pode levar anos para ser estabelecida. Por esse motivo, é importante que technical writers tenham argumentos convincentes para garantir que um processo, produto ou solução seja documentado.
Para chegar a uma solução eficaz, é fundamental entender as dificuldades dos times de desenvolvimento ou de produto em relação à produção de documentações e, juntos, traçar um plano de ação que ajude o processo de documentação. Esse processo é essencial e requer empatia e muito conhecimento para pensar na resolução dos problemas.
Além disso, na maioria das vezes as pessoas estão em sua primeira experiência com o processo de documentação técnica e, adicionar muitas etapas a essa nova prática, pode dificultar ainda mais a adoção de padrões.
O auxílio da evolução tecnológica
Para facilitar a adoção de padrões e a agilidade na criação de documentações, a evolução das ferramentas de tecnologia abriu um novo horizonte, possibilitando a utilização de soluções próximas às pessoas desenvolvedoras para facilitar a escrita e publicação das documentações técnicas, agindo como grandes aliadas e facilitadoras da implementação da cultura de documentação.
Mas, afinal, que ferramentas são essas e como usá-las? Este artigo foi pensado para apresentar para você uma ferramenta inovadora que pode ajudar em tudo o que sua mente consegue imaginar: a StackSpot.
StackSpot e a importância da otimização da jornada da pessoa desenvolvedora
A StackSpot é uma plataforma de desenvolvimento que tem como objetivo abstrair complexidades durante todo o processo de desenvolvimento. Embora seja uma ferramenta técnica voltada para devs, ela pode ser utilizada como um meio de otimização e automação de processos por outras áreas com dores relacionadas a processos que dependem de devs, como é o caso da documentação técnica.
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
Conceitos importantes para criar soluções com StackSpot
Para criar ou idealizar as soluções, é importante entender algumas funcionalidades e conceitos da StackSpot essenciais para o uso da plataforma na inovação, que são:
- Plugins: peças de tecnologia adicionadas ao código da sua aplicação para incluir capacidades ou servir como base de um projeto. Plugins podem ser do tipo app ou infra.
- Plugins do tipo app (aplicação): adicionam funcionalidades que auxiliam na criação e configuração de uma aplicação. Por exemplo, um Plugin que facilita a configuração dos parâmetros e informações de um template aplicado ao repositório de documentação.
- Plugins do tipo infra: adicionam funcionalidades que auxiliam na criação da infraestrutura em aplicações criadas com Plugins do tipo app.
- Actions: usadas para criar automações que facilitam processos no ambiente de desenvolvimento.
- Stack: usada para agrupar Plugins e Actions que são correlacionados a um mesmo tema ou tecnologia. Por exemplo: uma Stack de Java, que pode conter diversos Plugins e Actions relacionados ao desenvolvimento de aplicações com Java.
- Estúdio: usado para gerenciar os conteúdos publicados pelas pessoas desenvolvedoras de Plugins, Actions e Stacks. Em um Estúdio, você pode publicar Actions e Plugins, criar Stacks, e gerenciar o acesso a esses conteúdos com permissões individuais ou por equipes.
- Workspace: usado para gerenciar os recursos necessários para a criação de aplicações, configuração de ambientes e contextos para times específicos. Nele, você cria e configura ambientes para criar a sua aplicação em diferentes contextos, como ambientes de produção, desenvolvimento e homologação (testes). Também, pode configurar variáveis, acessos e recursos para cada contexto separadamente.
Tecnologias usadas na StackSpot
Além dos conceitos da alocação de recursos na plataforma, a manutenção e criação de soluções demanda o conhecimento de tecnologias como:
- YAML: linguagem de marcação utilizada para configurar os arquivos de Plugins e Actions. Por exemplo, adicionar campos para o envio e recebimento de parâmetros à pessoa usuária.
- JINJA: engine de template, que interpreta expressões utilizadas nos campos dos arquivos de Plugins e Actions para interpolar (“manipular”) os valores de parâmetros enviados e recebidos pela pessoa usuária.
- Linguagens de programação: utilizadas para a construção do código da estrutura de Plugins e Actions a fim de solucionar cenários mais complexos. Por exemplo, Java, Python, etc.
Como pensar na StackSpot como uma aliada para documentação técnica
A StackSpot conta com suporte nativo para que você possa documentar todos os recursos (Plugins, Stacks, Actions, etc) criados dentro da plataforma. Para cada recurso, você possui uma pasta exclusiva para adicionar os arquivos de texto e imagens das suas documentações. Essa pasta possui suporte para internacionalização dessas documentações para os idiomas português (Brasil) e inglês (Estados Unidos).
Também é possível utilizar a StackSpot em documentações que são ou compõem produtos. Normalmente hospedadas em repositórios dedicados e utilizadas por times que trabalham com a documentação técnica. A StackSpot pode ser utilizada como uma aliada para otimizar o tempo de concepção e escrita da documentação, além de agilizar processos de verificações ortográficas e revisões.
Para isso, é necessário que a documentação siga a metodologia de Doc as Code, em que é criada e mantida em um repositório Git e hospedada no GitHub de forma similar aos códigos-fonte, para que no final seja publicada em um site estático.
Além disso, a StackSpot possui a frente de AI, que pode ajudar na criação de soluções com uma base de conhecimento, que fornece todo o contexto necessário para criar novos documentos, responder perguntas sobre padronização da documentação e muito mais.
Conheça mais sobre a StackSpot AI no vídeo abaixo:
StackSpot como uma facilitadora de colaboração entre devs e Tech Writers
Aproximar a maneira de escrever uma documentação com a de programar pode ser um facilitador para que technical writers e devs diminuam conflitos comuns na rotina de documentação de software, confira a seguir os desafios mais frequentes:
- Pessoas desenvolvedoras no geral não são familiarizadas com processos de escrita, onde recorrem a modelos de documentações que não são adequados, ou não bem adaptados para documentar um certo tema, por exemplo. Ocasionando em documentações técnicas problemáticas, difíceis de ler ou de encontrar informações, algo frequente em documentos de produtos.
- Documentar gera uma carga cognitiva além da exigida para desenvolver uma solução, o que torna a adesão à cultura de documentação mais difícil. Isso pode resultar em resistência na colaboração do processo de escrita técnica e uso das ferramentas para documentar software.
- O foco da pessoa desenvolvedora é diferente da technical writer, ambas precisam alcançar o sucesso do produto, mas devs focam em como resolver o problema de users através de uma solução. Enquanto technical writers focam em informar como users devem usar a solução para resolver o seu problema da melhor forma.
Para resolver esses problemas, é essencial que technical writers se aproximem dos times de produto e desenvolvimento para mapear ações que devem ser otimizadas, para que o uso da solução seja um facilitador ao invés de um problema para as pessoas desenvolvedoras se preocuparem.
A importância da colaboração entre papéis para a criação de soluções
O desenvolvimento de soluções para documentação requer a contribuição de ambos os papéis: pessoa desenvolvedora e technical writer. Para transformar as ideias em realidade, é importante alinhar o responsável pelo desenvolvimento das soluções conforme a capacidade e tempo hábil dos papéis do projeto.
Considere, por exemplo, a seguinte separação de papéis para pensar em uma solução:
- Technical writer (TW): com seu conhecimento em documentação, o papel de TW nessa solução é mapear as dificuldades em relação à documentação, seja o uso de plataforma, ferramentas, como começar a documentar e padrões. Com essas informações é possível entender o que pode ser otimizado.
- Pessoa desenvolvedora: com seu conhecimento em desenvolvimento, independente da linguagem de programação, essa pessoa consegue abstrair as informações que a pessoa TW levantou para desenvolver essa solução e criar Plugins, Actions ou até mesmo utilizar a Inteligência Artificial durante o processo.
Dessa forma, technical writers precisam ter atenção aos processos e etapas que observam em relação à documentação técnica para criar oportunidades no desenvolvimento de soluções com StackSpot com o apoio das pessoas desenvolvedoras.
Caso de uso da aplicação de StackSpot em documentação técnica
Em primeiro lugar, para demonstrar como a StackSpot seria aplicada em um cenário real de documentação técnica, montamos um caso de uso com as etapas da criação de uma solução para um repositório de documentação.
1. Identificação
Primeiramente, ao observar seu cenário atual, Pedro, um Technical Writer, identificou que passava muito tempo arrumando termos na documentação técnica, levando até mesmo horas para padronizar os termos da solução.
2. Definição
Ao identificar o problema, Pedro decidiu anotar o que precisava fazer para a realização da tarefa. Dessa maneira, o resultado foi:
- Identificar como o termo deve ser escrito;
- Percorrer todas as páginas da documentação procurando e arrumando o termo.
3. Planejamento
Pedro conhece a StackSpot e logo entrou em contato com uma pessoa desenvolvedora do seu projeto para mostrar a dor que identificou e o processo para a criação de uma solução com StackSpot.
4. Desenvolvimento
Com o conhecimento do processo de Pedro e o conhecimento da solução da pessoa desenvolvedora, juntos, eles criaram um Plugin que:
- Identifica a forma que o termo deve estar na documentação; e
- Arruma todas as referências automaticamente nos arquivos.
5. Publicação
Por fim, após desenvolver e testar cenários de aplicação no repositório de documentação, o Plugin foi publicado como parte de uma Stack de documentação técnica na StackSpot.
O que podemos esperar da junção de StackSpot e documentação técnica
Com a criação de soluções para documentação utilizando StackSpot e, futuramente, StackSpot AI, podemos esperar grandes avanços em relação à qualidade das nossas documentações: otimizando o tempo de devs para construir documentações, e de technical writers, para o processo de padronização e estruturação das documentações técnicas e templates de documentação, por exemplo.
A ferramenta diminui a carga manual para focar em processos cognitivos que realmente precisam da expertise e conhecimento para acontecer, o que torna TWs, cada vez mais, agentes de transformação.
Como se aprofundar no tema
Como o tema StackSpot segue em uma crescente, precisamos continuar estudando e, certamente, nos capacitar para garantir a construção de soluções escaláveis e com uma boa qualidade.
Confira a seguir alguns links para se aprofundar no tema:
Por fim, a conclusão
Em resumo, nesse artigo, você entendeu um pouco mais sobre como a utilização de ferramentas como a StackSpot pode mudar a maneira que entendemos os processos de documentação técnica.
As informações e o caso de uso fornecido irão ajudar a exercitar quais etapas do trabalho em repositórios de documentação podem ser otimizadas utilizando StackSpot. Dessa maneira, trazendo ainda mais transformação para projetos de desenvolvimento.
