Jekyll: conheça a ferramenta de documentação de projetos
Entenda o que é e como documentar softwares, e conheça a ferramenta utilizada no Laboratório Bridge
Bianca Nocetti e Marina Soares
Gestão do conhecimento é o segredo de uma equipe que está sempre em evolução! No desenvolvimento de projetos, não é diferente. Preservação, manutenção e descentralização do conhecimento devem ser prioridades para os times.
E para que um processo de gestão seja bem-sucedido, a documentação tem um papel importante, contribuindo também para o desenvolvimento e aperfeiçoamento do produto. Com ela, é possível ter uma visão clara de como o projeto está e quais funcionalidades ele atende. Aí fica mais fácil identificar melhorias e novas possibilidades!
Mas como fazer isso? 🤔
Hoje a Bianca Nocetti, Product Owner no Bridge, fala sobre como documentar projetos com a ferramenta Jekyll. Bora aprender?
- O que é documentação de software?
- Etapas básicas para uma boa documentação
- Conheça a ferramenta que usamos para documentar projetos no Bridge
O que é documentação de software – e por que fazer isso?
A documentação é um material textual que times de engenharia, teste, produto e outros profissionais utilizam para realizar, descrever e registrar o trabalho desenvolvido.
Você pode estar pensando: “Mas, para que documentar um software? É só ter um código legível, com boa arquitetura e que siga as práticas de clean code”
E sim, todos esses quesitos são essenciais para um bom projeto, mas a documentação também é. Afinal, apenas os programadores têm o controle e o conhecimento em traduzir uma linguagem de alto nível. Com o material escrito, qualquer pessoa do time – seja ela desenvolvedora ou não – poderá acessar e entender o projeto.
Além disso, os documentos descentralizam o conhecimento sobre um determinado produto, o que torna as mudanças e evoluções da equipe muito mais fáceis. Ter um documento para consultar informações técnicas facilita a rotina de quem programa, evita retrabalho e contribui para a adaptação de novos integrantes à equipe.
Em projetos mais complexos, a documentação também deve registrar como funciona determinado algoritmo, diagramar fluxos de dados, a arquitetura do sistema, etc. Ou seja, tudo que for relevante para a compreensão do funcionamento do sistema como um todo.
Etapas básicas para uma boa documentação
As dicas podem parecer óbvias, mas são super importantes na hora de documentar um software. Dá uma olhada nas quatro características de uma boa documentação:
#1 Material objetivo
Evite alongar desnecessariamente as informações. Descreva apenas o que for útil.
#2 Fácil de entender e pesquisar
A estrutura da documentação deve ser pensada para facilitar a navegação e a busca das informações.
#3 Linguagem simples
Evite termos complexos e informações implícitas. Utilize linguagem clara, acessível e, se possível, aplique outros recursos para facilitar o entendimento, como imagens e diagramas.
#4 Descrições úteis para a equipe técnica
Além das regras de negócio, é importante documentar a parte técnica do produto. Aí entra arquitetura do sistema, funcionamento de algoritmos essenciais ou complexos, estrutura do banco de dados, diagramas de determinados fluxos de informação e outros.
Conheça a ferramenta que usamos para documentar projetos no Bridge
Aqui no Bridge, utilizamos uma ferramenta gratuita para realizar a documentação: o Jekyll. Ele é um gerador de sites estáticos que converte automaticamente vários arquivos, seja em HTML, css, javascript, markdown, entre outros.
Para versionamento, a ferramenta utiliza o GitHub, com branches, PRs, commits, etc. Além disso, não é necessário ter uma base de dados. A ferramenta possui sua própria hospedagem gratuita no GitHub Pages.
O Jekyll promove agilidade na escrita do conteúdo com Markdown, pois, ao contrário do HTML, não é necessário abrir e fechar diversas tags para formatar o texto, por exemplo.
Ou seja, é uma mão na roda na hora de documentar nossos projetos!
Para a realidade do Laboratório, o Jekyll foi a ferramenta que nos adaptamos melhor. E por aí, quais ferramentas estão no seu dia-a-dia de desenvolvimento? Conta pra gente nas nossas redes sociais!
@laboratóriobridge no Instagram 😉
Quer aprender mais com o Bridge? Você pode se interessar por:
- B_thinking: o modelo de processo de UX do Bridge, agora para todos!
- Design Review: a cerimônia que otimiza o trabalho de designers ágeis
O Laboratório Bridge atua no Centro Tecnológico da Universidade Federal de Santa Catarina (CTC/UFSC), com equipes formadas por bolsistas graduandos, pós-graduandos e profissionais contratados. É orientado por professores do CTC e do Centro de Ciências da Saúde (CCS/UFSC).
Desde 2013, desenvolvemos sistemas e aplicativos para gerenciamento da saúde pública em parceria com o Ministério da Saúde e a Agência Nacional de Vigilância Sanitária (ANVISA).
