Para iniciar, se você é um desenvolvedor ou trabalha com desenvolvimento de software, já deve ter se perguntado sobre a importância da documentação de software no seu cotidiano.
Você também pode ouvir esse conteúdo:
A documentação de software é um conjunto de informações escritas, acompanhadas por vídeos e imagens que servem como guia, isto é, um tutorial, para o uso de um serviço ou programa. Ela ajuda a esclarecer dúvidas, explicar a funcionalidade e o funcionamento do sistema, e garantir que todos os usuários da sua tecnologia tenham acesso às informações necessárias.
Portanto, com foco nesse tipo de documentação, preparamos esse material para explicar sobre o papel da documentação no desenvolvimento seguro e apresentar o Conviso Docs, a documentação de software da Conviso Platform.
O papel da documentação de software
A documentação de software técnica representa uma fonte de orientação imprescindível para desenvolvedores, independente do nível de habilidade. É muito comum ouvir que uma documentação ruim pode ser o maior obstáculo para uso de um produto ou a realização de um processo durante o desenvolvimento de uma aplicação.
Para entender o que torna a documentação boa, precisamos primeiro compreender o objetivo da documentação. Qual é a sua finalidade? Por que é tão importante ter uma documentação eficaz?
É simples, uma documentação boa resolve as dúvidas dos desenvolvedores e de outros profissionais envolvidos
Em uma pesquisa de estudo de caso sobre o tema, foi observado que programadores geralmente levantam as mesmas perguntas antes de começar a desenvolver. Nessa pesquisa, eles categorizaram todas essas perguntas em 5 categorias:
- Como (código de exemplo): Como usar a API X? Como implementar o recurso Y?
- O que (leitura de código específico): O que faz esse script? Qual o nome da enumeração?
- Onde (localização de código): Onde está o código para fazer X? Onde configuramos as variáveis de ambiente para Y?
- Por quê (determinar impacto): Por que minha mudança não funcionou?
- Quem e quando (metadados): Quem editou este código e quando? Quem pode ajudar a revisar este código?”
Em resumo, uma boa documentação deve:
- Ser fácil de encontrar.
- Ser fácil de ler/escrever e atualizar.
- Ser atualizada e clara.
- Oferecer o contexto completo.
Além disso, a documentação é essencial para auxiliar no processo de desenvolvimento seguro, orientando programadores sobre as melhores práticas e prevenindo erros comuns.
Saiba também, um pouco mais sobre a Conviso Platform – de devs para devs.
Por que a documentação é tão importante inclusive quando se trata de AppSec?
A princípio, é simples: ela pode ter um impacto enorme no negócio e, consequentemente, em seus usuários. Imagine se um único tópico da documentação pudesse alertar os desenvolvedores sobre um possível risco de segurança que eles não haviam considerado antes em seu código. Isso evitaria vários problemas!
Do mesmo modo, ela pode ser uma fonte primária de aprendizado sobre desenvolvimento seguro para sua linguagem. Suponha que um desenvolvedor não tenha pensado em proteger seu software contra SQL Injection, nessas circunstâncias, a documentação de software pode abordar esse risco ensinando sobre como evitar esse tipo de problema. Veja mais neste artigo.
Entretanto, é válido ter em mente a documentação de software dos produtos de segurança que você utiliza. Essa documentação é essencial para garantir que você esteja ciente das capacidades e recursos deste produto, bem como de sua utilização correta e eficiente. Ao ter conhecimento dessa documentação, você pode maximizar o suporte oferecido por essa ferramenta em seu processo de desenvolvimento seguro.
Conheça o Conviso Docs – documentação da Conviso Platform
A Conviso Docs é a documentação oficial da Conviso Platform e é uma ferramenta essencial para que nossos usuários desenvolvedores possam utilizar nossos produtos de forma eficiente e autônoma. Ela pode ser acessada por este link.
Do mesmo modo, na Conviso Docs, você encontrará informações gerais sobre a plataforma e orientações para cada uma das funcionalidades, incluindo questões comuns relacionadas ao uso do produto.
Além disso, há informações mais técnicas para pessoas desenvolvedoras, SREs e profissionais de segurança, com descrições detalhadas dos diferentes componentes do produto, como a API, integrações e CLI.
Assim também, a documentação é de código aberto e todos são convidados a colaborar!
Como atualizar nossa documentação de software
Da mesma forma, nós acreditamos na colaboração como a chave para evoluir e tornar nossa documentação de software cada vez mais completa e precisa. Aqui estão as etapas que você precisa seguir para contribuir:
- Faça um fork do repositório e crie uma branch seguindo o padrão “feature/nome_da_branch”.
- Realize suas alterações na branch de seu fork, certificando-se de que ela esteja sempre atualizada com a branch principal.
- Abra uma solicitação de Pull Request (PR) no GitHub, detalhando todas as alterações que você fez e as razões por trás delas.
Agora é só esperar pela nossa equipe avaliar sua PR e, se aprovada, suas contribuições serão incorporadas à nossa documentação de software. Para verificar o processo de contribuição completo, é só acessar o CONTRIBUTING.md.
Além do processo mencionado acima, incentivamos nossos usuários a levantar dúvidas, correções, críticas e sugestões sobre nossa documentação por meio da criação de “issues” em nosso repositório no GitHub.
Não deixe a documentação de lado!
Para finalizar, neste artigo é possível entender a importância de manter e escrever documentações com clareza, como funcionam e como facilitar e apoiar o dia a dia da pessoa desenvolvedora. Buscamos destacar a importância desse recurso para aprender sobre desenvolvimento seguro, sobretudo ao entender acerca dos riscos ao utilizar uma tecnologia de maneira não adequada.
Afinal, a colaboração é fundamental para manter a documentação atualizada e completa. Ao contribuir para a documentação, os usuários podem ajudar a evoluir e tornar a documentação mais precisa e completa.
Autores:
Gabriel Galdino – Developer Advocate
Giovanni Martins – Software Engineer
