Documentação

Antes de começarmos a programar em nossos projetos, é importante aprender como escrever a documentação de um projeto.

Documentação de um projeto refere-se a um conjunto de instruções e informações organizadas que descrevem o objetivo, a estrutura, o funcionamento e a utilização de um projeto. Ela torna o projeto compreensível e acessível para pessoas desenvolvedoras, usuárias finais e outras interessadas, facilitando a colaboração, a manutenção e a evolução do projeto ao longo do tempo.

Em termos práticos, a documentação de um projeto nada mais é do que um conjunto de arquivos de texto que explicam tudo sobre o próprio projeto.

Que tipos de documentações existem?

Mas e no mundo real, como são essas documentações? Existem diversos tipos, dependendo do projeto e de quem vai utilizá-lo. Aqui estão alguns exemplos:

Manual do Usuário

• Explica como o usuário final pode interagir com o projeto.

• Exemplo: Você criou um jogo de campo minado e precisa ensinar os jogadores como jogar, descrevendo as regras e o que cada botão faz.

Guia de Instalação

• Ensina como instalar ou configurar o projeto.

• Exemplo: Você desenvolveu um aplicativo de música e quer mostrar aos usuários como baixá-lo e instalá-lo no celular ou computador.

Guia para Desenvolvedores

• Ajuda outras pessoas a entenderem o código e contribuírem com ele.

• Exemplo: Você criou um site e precisa explicar para um colega desenvolvedor como o código funciona, como modificar algo e como publicar as alterações.

Licença de Uso

• Define as condições em que o projeto pode ser usado.

• Exemplo: Você desenvolveu uma ferramenta que outros programadores podem usar e quer definir se ela é gratuita ou paga, ou como pode ser distribuída.

Registro de Alterações (Changelog)

• Lista as mudanças feitas no projeto ao longo do tempo.

• Exemplo: Quando você lança uma nova versão do projeto, registra o que foi corrigido, adicionado ou melhorado.

FAQ (Perguntas Frequentes)

• Responde dúvidas comuns sobre o projeto.

• Exemplo: Para um aplicativo, você pode incluir perguntas como "Como faço para atualizar?" ou "E se o app travar?".

Exemplos de Uso

• Mostram como usar o projeto na prática, com explicações claras.

• Exemplo: Você criou um programa que ajuda a calcular o preço de produtos com desconto e mostra como utilizá-lo em diferentes cenários: "Se um produto custa R$ 100 e está com 20% de desconto, o resultado será R$ 80."

Por que começar pela documentação?

• Porque todo projeto precisa de documentação: Um projeto, por mais avançado que seja, não será útil se ninguém souber como usá-lo. Uma boa documentação é o que conecta o seu trabalho às pessoas que podem se beneficiar dele. ter documentações:

• Porque é simples: Comparado a programar em linguagens como Python ou JavaScript, criar documentação (especialmente usando Markdown) é relativamente fácil. Então é um ótimo primeiro passo para interagir com repositórios no GitHub.

• Porque é necessária em qualquer linguagem: Não importa a tecnologia utilizada, você sempre precisará documentar seus projetos.

• Padrões comuns no GitHub: No GitHub, as documentações geralmente usam a mesma notação (Markdown). Por isso, aprender Markdown facilita a criação de documentação de qualidade e legível.

Sem documentação, seu projeto perde valor

Um projeto incrível, com um código impecável, perde sua utilidade se ninguém souber como usá-lo ou como contribuir com ele. A documentação é o que transforma o código em algo útil e acessível.

Próximos Passos

Agora que você já entende a importância da documentação em um projeto, chegou a hora de dar o próximo passo: aprender como escrever documentações diretamente no GitHub de forma clara, organizada e eficiente. Para isso, vamos usar o Markdown, uma ferramenta simples e poderosa que facilita a criação de conteúdos bem estruturados e acessíveis.