Documentação da Snyk: nossa trajetória até aqui

Como responsável pela documentação para usuários da Snyk nos últimos três anos, acompanhei muitas melhorias em nossa documentação.

Uma cultura de contribuição

Criamos uma cultura de contribuição única para nossa documentação. Centenas de colaboradores ativos da Snyk criam, atualizam e aprimoram continuamente o conteúdo.

Uma das principais formas de fazer isso foi adotar um processo de documentação como código em nossa equipe.

Documentação como código

Em poucas palavras, um processo de “documentação como código” significa que a escrita segue um fluxo semelhante ao desenvolvimento de código e, em geral, adota plataformas e ferramentas práticas para desenvolvedores. Por exemplo, a documentação da Snyk usa a plataforma GitBook, que utiliza um conjunto de processos semelhante ao Git para gerenciar alterações, oferece uma interface de edição simples e sincroniza com um repositório do GitHub para o conteúdo armazenado em arquivos Markdown.

Esse processo viabilizou plenamente as contribuições. Ao eliminar a curva de aprendizado acentuada e as restrições de acesso associadas às ferramentas profissionais de autoria, mais pessoas podem colaborar com o conteúdo sem arcar com custos de licenciamento proibitivos.

Como a Snyk faz documentação

Na Snyk, nossas equipes de desenvolvimento escrevem o primeiro rascunho da documentação de novos recursos no ambiente de escrita do GitBook. Isso gera envolvimento e senso de responsabilidade, permitindo que contribuam rapidamente com o conteúdo, sem precisar transferir e reformatar manualmente informações de outras fontes. Como começamos a desenvolver a documentação antes de os recursos entrarem em teste, ela costuma estar pronta e publicada quando o recurso chega à fase de beta fechado, dando aos usuários acesso rápido e fácil às informações.

Treinamos, apoiamos e incentivamos todos os colaboradores, oferecendo ajuda durante a edição (com a ferramenta Grammarly) e garantindo que as revisões e alterações sigam um padrão. Cada novo integrante das equipes de P&D recebe orientações específicas e é acompanhado por redatores para aprender como contribuir e pedir ajuda. O apoio desde o início e a automação são essenciais para ampliar a documentação com qualidade — por isso, são pontos centrais da abordagem da Snyk.

Em resumo, a Snyk segue duas abordagens:

• Shift-left: teste seu código mais cedo — enquanto o escreve, e não apenas antes de lançá-lo.

• Shift-down: deixe os desenvolvedores fazerem os testes, em vez de equipes especializadas em segurança.

Nossos processos de documentação seguem esse mesmo modelo. Colaboração, escala e automação fazem parte do nosso DNA cultural.

Resultados da cultura de contribuição

Ao transformar a forma como a Snyk cria documentação, chegamos ao início de 2024 com mais de 250 colaboradores ativos. Nos últimos dois anos, fizemos mais de 6.000 alterações e melhorias na documentação — quase 10 por dia.

As equipes participam e se envolvem, e os redatores técnicos são reconhecidos como facilitadores dos recursos, não como obstáculos. Evitamos corridas de última hora para documentar um recurso, que podem atrasar o lançamento, resultar em documentação de baixa qualidade ou ambos.

O que estamos fazendo: experiências, perfis e opiniões dos usuários

Agora, nosso foco é melhorar a qualidade da documentação, alinhá-la às experiências e aos perfis dos usuários da Snyk e oferecer mais conteúdo prescritivo, com recomendações claras.

Alinhamento às experiências dos usuários

Estamos transformando a arquitetura da informação da documentação. Sempre oferecemos conteúdo “descritivo” claro, que explica como usar os produtos da Snyk. No entanto, temos pouco conteúdo “prescritivo” para recomendar boas práticas ou apresentar exemplos detalhados. Sem essas orientações, os usuários precisavam definir seus próprios caminhos de implementação, pois a estrutura da documentação não correspondia às suas experiências, jornadas ou perfis.

Onde começamos

Esta era nossa estrutura em 2022, organizada em torno dos produtos da Snyk:

Descrevendo a jornada

Agora, temos uma arquitetura da informação simplificada e direcionada, alinhada à experiência linear do usuário:

Nossa jornada de conteúdo inclui:

• Seções iniciais que descrevem a primeira etapa da experiência do usuário (“integração”), incluindo um Guia de início rápido para avaliar as funcionalidades e uma seção Implemente a Snyk com orientações mais estratégicas para planejar a implementação na sua empresa.

• Em seguida, detalhamos as integrações com a Snyk, incluindo as integrações com o Git para conectar seus repositórios de gerenciamento de código-fonte à Snyk e as integrações de CI/CD para estratégias de implantação de longo prazo.

• Depois, abordamos as operações do dia a dia em Análise com a Snyk, incluindo o uso de cada produto da Snyk, como o Snyk Open Source.

• Também incluímos tarefas gerais de administração na seção Administração da Snyk.

• Para concluir, apresentamos duas áreas independentes: CLI e API.

Alinhamento aos perfis dos usuários

Identificamos vários perfis de usuários da Snyk que consultam nossa documentação com frequência: desenvolvedores, administradores e responsáveis pela implementação, além de profissionais de AppSec.

Cada perfil tem necessidades de informação diferentes. Por isso, queremos garantir que a documentação seja fácil de acessar e navegar para todos, com acesso às áreas de conteúdo mais relevantes para cada um.

Por exemplo:

• Desenvolvedores: oferecemos conteúdo sobre Guia de início rápido e Analise com a Snyk

• Administradores/responsáveis pela implementação: podem se concentrar em Configuração empresarial e Administração da Snyk

• Segurança de aplicações: foco em Gerenciamento de riscos

Mais recomendações claras

Ao longo dos anos, acumulamos muito conhecimento sobre como ajudar os clientes a implementar a Snyk com sucesso, desde a integração inicial até o uso diário. Esse conteúdo orientado inclui casos de uso detalhados, tutoriais passo a passo, recomendações e outras orientações prescritivas. Estamos reunindo esse conhecimento e publicando o conteúdo.

Esse conteúdo ajudará todos os usuários a planejar cada etapa da experiência com a Snyk. Além disso, sabemos que nosso mercado empresarial em expansão precisa de mais materiais desse tipo, com treinamentos escaláveis e acessíveis para que as empresas possam conduzir programas eficientes de integração à Snyk.

Começamos a criar esse conteúdo com os guias de implementação da Snyk na seção Implemente a Snyk.

Próximos passos

Nossa jornada com a documentação está longe de terminar.

Estamos começando e planejando vários projetos empolgantes para a documentação em 2024, incluindo:

• Adicionar elementos consistentes de “storytelling” ao longo da documentação, que os clientes possam usar como modelos.

• Incorporar recursos úteis de IA à experiência do usuário para responder rapidamente às suas dúvidas.

• Integrar o conteúdo mais diretamente à experiência do usuário, para que você encontre ajuda com mais rapidez e inteligência.

• Adicionar um changelog detalhado e consistente com todas as alterações funcionais da Snyk.

• Ampliar e publicar um catálogo completo de mensagens de erro.

Então, fique de olho na documentação para saber mais!