jekyll-laboratorio-bridge-documentação-software
Tempo de Leitura: 3 minutos

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:


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).

LinkedIn
WhatsApp
Facebook
Twitter

Posts Relacionados

Cinco insights sobre inovação e trabalho que aprendemos com Gino Terentim

Tempo de Leitura: 6 minutos O encerramento do evento oficial de 10 anos do Bridge foi uma talk exclusiva com Gino Terentim! Um dos grandes nomes em gerenciamento de projetos e agile, Gino acreditou no nosso propósito e se voluntariou para falar sobre inovação, colaboração e longevidade organizacional.

Como ser bridger também significa compartilhar conhecimento, trouxemos cinco insights que tivemos durante a palestra.

Shopping Basket