Motivação para a importância da documentação de sistemas

Veja abaixo o exemplo de um sistema de votação:

1 def votar():
2  while True:
3    try:
4      numero = int(input("Digite o número do candidato: "))
5      if numero in candidatos:
6        confirmar = input(f"Você escolheu {candidatos[numero]}. Deseja confirmar a votação? (s/n): ").lower()
7        if confirmar == 's':
8          print("Votação concluída com sucesso! Obrigado pelo voto!")
9          break
10      else:
11        print("Candidato inexistente ou número inválido! Insira novamente.")
12    except:
13      print("Entrada inválida! Por favor, insira um número.")
14 votar()

Vamos analisar o programa citado acima:

Função votar

Obs.: o programa tem uma base de dados contida em um dicionário, armazenando números e nomes dos candidatos na chapa.

Obs. 2: O try/except foi usado para tratar o erro no caso de o valor digitado não ser um inteiro. Caso essa sentença não esteja ali, o programa apresentará um erro. 

Entrada: 

1. A entrada deve ser de um número válido correspondente ao que está armazenado no dicionário.

Processamento:  

2. Um loop WHILE contínuo permite que o usuário (eleitor) insira o número do candidato. Isso é importante para que ele possa continuar na mesma tela caso haja um erro de digitação.

3. Após a digitação, o sistema verifica se o número inserido está na base de dados.

4. Se o número for válido, solicita confirmação do usuário.

5. Se o usuário confirmar ('s'), a votação é concluída e o loop é interrompido.

6. Caso contrário, ou seja, se o número for inválido ou a entrada não for um número, uma mensagem de erro na linha 11 ou 13 é exibida e o eleitor poderá votar novamente.

Saída:

7. A saída antes da confirmação exibirá na tela o candidato e o número e ao final da confirmação uma mensagem de despedida ao eleitor. 

O programa simula uma das funcionalidades da urna eletrônica: o usuário, no caso o eleitor, deve inserir os dados correspondentes ao candidato que deseja votar. Claro que esse programa pode ter funções adicionais, interface gráfica e uma API integrada para coletar dos votos, dentre outras funcionalidades a tornar o sistema cada vez mais completo. Para agilizar o processo a um responsável que deve adicionar tais funcionalidades ao programa, a sua documentação precisa ser a mais clara possível.  

Uma coisa a se refletir: E se o programa não tivesse tais descrições? Não seria mais confuso ou então poderia gerar até perda de tempo e engajamento por parte do leitor? Nesse caso, para argumentar sobre o ponto de vista em um cenário de ambiente de programação e até de se livrar um pouco dos feedbacks críticos que aparecem por aí, a documentação é vista como um pilar para o melhor entendimento aos desenvolvedores sobre o que, como e o porque de seguir um modelo de ideia construído de seu sistema, claro que dentro de boas práticas.

• Clareza na documentação. 
• Mais informação sem escrever um textão. 
• Seja direto ao ponto na informação. 
• Não repita você mesmo.
• Faça revisões e evite os erros ortográficos.
• Utilize a inteligência artificial a seu favor!

Ninguém é obrigado a entender cada linha da script em questão. Então, existe a máxima de que cada sentença pode representar uma ideia de uma parte de um subsistema que precisa ser feito para o todo funcionar. Sabe-se que há um entendimento de que fazer programas complexos exigem muita prática dentro de um contexto que só o programador conseguirá entender dentro de um cenário em que é fundamental a compreensão da sua regra de negócios. Mas, isso não deve refletir em um desafio para que o leitor ou colaborador tentar entender todos os detalhes dito cifrados exclusivamente a uma parcela de pessoas mais experts. É interessante construir sistemas, mesmo que complexos, mas que haja simplicidade em sua implementação. Portanto, é importante saber como, onde e quais os benefícios em documentar sistemas com qualidade, para:  

Comentários inline (dentro do código): Comentários inline são essenciais para explicar trechos específicos do código. Eles ajudam outros desenvolvedores a entender a lógica por trás de determinadas implementações, facilitando a manutenção e a atualização do código. Comentários bem escritos podem prevenir erros e melhorar a eficiência da equipe, pois reduzem o tempo necessário para entender e modificar o código2.

Comentários outline (fora do código ou documentação externa): Comentários outline, ou documentação externa, fornecem uma visão geral do sistema, incluindo sua arquitetura, design e fluxos de trabalho. Eles são úteis para entender como diferentes partes do sistema interagem entre si e como o sistema deve ser utilizado. Esse tipo de documentação é crucial para a manutenção a longo prazo e para a integração de novos desenvolvedores, pois oferece um contexto mais amplo que não pode ser capturado apenas com comentários inline

Contribuição a comunidade: Uma documentação bem elaborada facilita a contribuição de novos desenvolvedores e membros da comunidade. Ela fornece um guia claro sobre como o sistema funciona, quais são suas funcionalidades e como contribuir de maneira eficaz. Isso aumenta a colaboração e acelera o desenvolvimento, pois os novos colaboradores podem entender rapidamente o projeto e começar a contribuir sem precisar de muita orientação.

Faq's (fórum de perguntas frequentes): Um fórum de perguntas frequentes (FAQs) é uma excelente ferramenta para resolver dúvidas comuns de usuários e desenvolvedores. Ele pode reduzir significativamente o tempo gasto respondendo a perguntas repetitivas e fornecer soluções rápidas para problemas comuns. Além disso, um FAQ bem mantido pode servir como uma base de conhecimento valiosa, ajudando a identificar áreas do sistema que podem precisar de melhorias ou esclarecimentos adicionais4.

READ-ME (descrição completa possível do sistema): O arquivo README é geralmente o primeiro ponto de contato para qualquer pessoa interessada no projeto. Ele deve fornecer uma visão geral clara e concisa do sistema, incluindo suas funcionalidades principais, requisitos de instalação, instruções de uso e exemplos de código. Um README bem escrito pode atrair novos usuários e desenvolvedores, facilitando a adoção e a contribuição para o projeto.

Portal para contato : Um portal para contato permite uma comunicação assíncrona eficaz entre os desenvolvedores e outras partes interessadas, como usuários finais, clientes e colaboradores. Ele pode incluir fóruns, sistemas de tickets ou canais de comunicação direta, como e-mail ou chat. Esse portal é crucial para resolver problemas, receber feedback e discutir melhorias, garantindo que todas as partes interessadas estejam alinhadas e informadas.