Fala, pessoal. Tudo bem? No artigo de hoje trarei algumas discussões muito debatidas, e até, retratadas em algumas cadeiras de cursos superiores de TI: qual a importância de ter uma boa documentação no seu projeto? Existe algum tipo de documentação que se aplica a todos os tipos de projeto?
Nesse artigo falo um pouco sobre esses temas, e por fim, faço uma sugestão de ferramenta que você pode usar para documentar sua aplicação front-end.
O que é uma documentação de um projeto?
Se levado ao pé da letra, uma documentação é uma espécie de “mapa” que qualquer profissional de TI pode usar para entender um projeto.
Nele, é preciso conter algumas informações importantes como nome do projeto, descrição, produtos agregados, intuito, fluxograma, entre outras questões principalmente ligadas às regras de negócio.
Uma vez que um projeto é escalável, diminuir a curva de aprendizagem para novos integrantes é essencial quando ele alcança maiores proporções, já que uma das consequência de um projeto que cresce é a necessidade de ter mais profissionais atuando nele.
Assim, não só novos integrantes são beneficiados, mas também colaboradores já presentes também. Isso porque em um ambiente muito mais estruturado, é possível verificar na documentação pontos de melhorias ou até possíveis mudanças.
Observe nesse caso um esboço de uma documentação. Mesmo que a aplicação seja simples, rapidamente é possível saber o que ela é, as tecnologias usadas e um pouco sobre a interface dela:
Algumas dicas para escrever sua documentação
Mesmo que não exista uma regra definitiva para escrever documentações, é importante lembrar alguns pontos. Esses pontos são comuns em grande parte das documentações, uma vez que eles se encaixam na maior parte delas.
Utilizar ferramentas para criar a documentação
Existem diversas ferramentas disponíveis que, com algumas configurações, ajudam a construir uma documentação para sua aplicação.
Nem todas vão se encaixar para todos os tipos de documentação ou projetos, mas vou listar algumas ferramentas famosas para isso:
– Bizagi Modeler
– Heflo
– BPMN.io
– Storybook
Obviamente, nem todas essas ferramentas vão se encaixar com a necessidade de todos os projetos, porém, ter uma ferramenta, principalmente de fácil acesso, é essencial.
A documentação do projeto deve ser acessível para que seja possível consultar e editar de forma rápida caso precise.
Definição de responsabilidades
Geralmente, grande parte dos projetos tem diversos profissionais atuando nele.
Por exemplo, em um projeto de software para web, é comum se ter um desenvolvedor front-end, um desenvolvedor back-end, um DevOps, um profissional responsável por testar a aplicação e o líder do projeto.
Seguindo esse cenário, é interessante que cada profissional escreva e detalhe sobre as questões relativas a sua área presentes no projeto, porque assim eles saberão em detalhes como estão funcionando as regras de negócio e fluxos da aplicação.
O desenvolvedor front-end pode documentar como está a padronização dos componentes visuais do software, por exemplo.
Já o responsável por testar a aplicação pode documentar como está o padrão de testes do software e descrever como é feito cada um deles.
O formato não é o mais importante
Apesar de escolher uma ferramenta para documentar o projeto, assim como escolher como ela vai ser feita e acessada sejam pontos importantes, não é preciso dar o foco maior neles.
O time do projeto precisa selecionar a forma mais viável para que todos acessem a documentação, assim como é preciso que a documentação fique clara e objetiva com as regras do projeto.
Uma alternativa para facilitar isso, é começar a documentação desenhando um macroprocesso. O mesmo busca fazer uma versão generalizada do projeto, como ciclos de vida e regras de negócio, e a partir disso, ir detalhando os pontos que também são importantes.
Storybook
Como já citado aqui, o Storybook é uma ótima ferramenta para documentar um software.
O mesmo é focado em documentar e testar componentes visuais, ou seja, do front-end.
Com ele é possível criar componentes e páginas isoladas, cada um seguindo uma regra própria.
Essa ferramenta se torna muito útil principalmente em aplicações escaláveis, porque ter padrões de componentes visuais é essencial para a usabilidade do usuário, e para a identificação visual do software.
A seguir mostro um exemplo de um botão simples, o mesmo pode ser padronizado para todo o seu software:
Conclusão
Com isso, é possível entender que investir em uma documentação de qualidade é quase que indispensável para o crescimento de um software ou projeto.
Com ele, pontos como segurança, implementação de novos colaboradores e a continuidade do projeto ficam mais consolidados, uma vez que, toda a ideia e regras do projeto são escritas e detalhadas.
Veja também…
Boas práticas de programação em Java para quem está tentando entrar na área de trabalho
