DS & II

Capítulo 16 - Documentação de Software

Leitura de 5 min

🚀 Capítulo 16: Documentação de Software (Tema: Indiana Jones)

NOTE

Este capítulo utiliza a temática de Indiana Jones para explicar a Documentação. Sem o Diário do Graal cheio de anotações, Indiana Jones teria morrido na primeira armadilha do templo!

1. 🎯 Objetivo da Aula

Compreender a importância da Documentação de Software, conhecendo os diferentes tipos (para usuários e para desenvolvedores) e o conceito de “Documentação como Código”.

2. 🏢 O Cenário Prático (Seu Desafio)

No filme Indiana Jones e a Última Cruzada, o pai do Indiana passa a vida inteira estudando e anotando tudo o que descobre sobre o Santo Graal em um pequeno caderno: o Diário do Graal. Quando o pai é sequestrado, Indiana usa esse diário para decifrar os enigmas, desativar as armadilhas e encontrar o caminho correto. Sem aquele documento, ele jamais teria conseguido!

No desenvolvimento de software, acontece algo muito comum e triste: um programador passa 2 anos criando um sistema complexo sozinho. Um dia, ele recebe uma proposta de outra empresa e vai embora. Quem entra no lugar dele olha para aquele milhão de linhas de código e se sente em um templo cheio de armadilhas mortais! A Documentação é o Diário do Graal do seu projeto! Ela serve para que outras pessoas consigam entender, usar e dar manutenção no seu sistema sem precisarem adivinhar o que você pensou. Seu desafio é escrever o diário do seu projeto!

🧠 Fundamentos: A Teoria Traduzida

Existem basicamente dois grandes tipos de documentação em um projeto de software:

👥 1. Documentação para o Usuário:

É o manual de instruções. Serve para quem vai usar o sistema.

  • Foco: Como criar uma conta? Como emitir um relatório? O que fazer se esquecer a senha?
  • Linguagem: Simples, sem termos técnicos difíceis.

💻 2. Documentação para o Desenvolvedor (Técnica):

Serve para quem vai dar manutenção ou continuar construindo o sistema.

  • Foco: Como instalar o projeto no meu computador? Qual banco de dados ele usa? Como as tabelas se relacionam? Para que serve essa função complexa?
  • Linguagem: Técnica e precisa.

📄 O Arquivo README.md:

É o documento mais importante de qualquer repositório de código moderno (como no GitHub). É a “capa” do projeto. Um bom README.md deve conter:

  1. O que o projeto faz.
  2. Como instalar e rodar o projeto na minha máquina.
  3. Quais tecnologias foram usadas.
  4. Como contribuir com o projeto.

4. 📖 Exemplo Guiado: Documentação como Código

Antigamente, as empresas escreviam manuais gigantes em arquivos do Word que ficavam guardados em gavetas e ninguém lia. Hoje, usamos o conceito de Docs as Code (Documentação como Código):

  • Nós escrevemos a documentação usando arquivos de texto simples (como o formato Markdown .md).
  • Esses arquivos ficam salvos dentro da mesma pasta do código do projeto.
  • Eles passam pelo Git igual ao código. Se você mudar uma função no código, você já atualiza o arquivo .md no mesmo commit! Assim a documentação nunca fica velha!

5. 🛠️ Prática Obrigatória 1: Onde colocar a informação?

Imagine que você está escrevendo a documentação de um sistema de vendas. Diga se a informação abaixo deve ir na Documentação do Usuário ou na Documentação do Desenvolvedor:

  1. “Para rodar o projeto localmente, execute o comando npm install no terminal.”
  2. “Para aplicar um cupom de desconto, digite o código no campo ‘Cupom’ e clique em ‘Calcular’.”
  3. “O sistema usa criptografia SHA-256 para guardar as senhas na tabela tbl_usuarios.”

6. 🛠️ Prática Obrigatória 2: O Código se explica sozinho?

No capítulo de Clean Code, vimos que um código bem escrito quase não precisa de comentários.

  1. Se o código já é limpo e fácil de ler, nós ainda precisamos criar arquivos de documentação (como o README.md) explicando o projeto? Por quê?

7. 📤 Instruções de Entrega (GitHub Desktop + Microsoft Teams)

  1. Faça o Commit: No GitHub Desktop, digite a mensagem (ex: Finaliza Capítulo 16 EngSoftware) e clique em Commit to main.
  2. Envie para a Nuvem (Push): Clique em Push origin.

8. 📂 Estrutura de Pastas

extra_engenharia_de_software/
├── README.md (Documentação principal)
└── capitulos/
    └── capitulo_16_documentacao.md

💡 Checkpoint de Lógica

Escrever documentação dá preguiça na hora. Mas lembre-se: o maior beneficiado pela documentação pode ser você mesmo no futuro, quando precisar mexer em um código que você escreveu há 6 meses e não lembra mais de nada!

10. 🔥 Desafio de Fixação

Pesquise o que significa a linguagem de marcação Markdown e aprenda a fazer títulos, listas e links usando ela.

🔑 Gabarito de Código/Fórmulas

Gabarito da Prática 1:

  1. Documentação do Desenvolvedor (Usuários comuns não usam terminal nem comandos npm).
  2. Documentação do Usuário (Instrução de uso do sistema).
  3. Documentação do Desenvolvedor (Detalhes técnicos de banco de dados e segurança). Gabarito da Prática 2:
  4. Sim! O Clean Code ajuda a entender o código linha a linha. Mas a documentação serve para dar a visão geral (o que o sistema faz, como instalar, qual o objetivo do projeto). Um programador novo não deve precisar ler todo o código-fonte para descobrir do que se trata o projeto!

← Capitulo Anterior | Proximo Capitulo →

Visão de gráfico

Backlinks