15 de julho de 2018

DocSoul: uma cultura

Cada um dá um nome diferente para isso que tratarei neste post, porém estamos falamos basicamente do ato de, ao codificar, documentar simultaneamente, redigir um simples tutorial com o mínimo necessário para que outro desenvolvedor ou até mesmo para que você futuramente tenha um fácil entendimento em cima do seu código e suas tomadas de decisões lógicas.

Apelidada pela byCoffee de DocSoul, essa metodologia/prática tem ajudado muito e tem seu destaque por não ser atrelada à nenhuma linguagem ou situação específica. Esta é chamada assim pois acreditamos que o desenvolvedor sempre coloca uma parte de si no código, o que é natural e excelente, a questão é passar isso para a documentação.

Nós temos o costume de documentar usando Markdown Text, principalmente por causa dos repositórios de código (Github, Gitlab, etc) usarem como padrão os arquivos .md, para isso muitas vezes, usamos algum plugin do editor de texto ou até mesmo a plataforma Dillinger, que é minha favorita por sinal!

A seguir darei um exemplo de uma situação onde foi criada uma Navbar:

Situação 1 (Código HTML)

Estrutura do menu:

  • Home
  • Perfil
  • Contato
  • Blog
  • Administrador
    • Coletar
    • Enviar
    • Receber
  • Sair

Documentação:
Esta não precisa explicar detalhadamente a navbar, neste caso, este código teria um DocSoul como este:
Versão PDF
Versão Markdown

Porém, a situação acima é muito simples, agora imagine uma navbar com 10 opções tendo em cada delas por volta 15 sub opções, o ideal é que quando alguém perguntar onde fica uma específica tela da aplicação seja fácil de encontrar com sua respectiva rota/função.

Em um caso como este, é interessante que a documentação demonstre, à grosso modo, o que cada item faz, se redireciona para uma url externa ou se até mesmo, ao clicar, executa uma função dentro do código.


Por enquanto é isso pessoal, espero que eu tenha conseguido passar para vocês um pouco sobre DocSoul!

Em breve farei alguns appends neste post, com exemplos em diferentes situações e linguagens!

Fique à vontade para comentar, tirar suas dúvidas e/ou fazer sugestões.

Grande abraço!

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *