Pular para conteúdo

Aula 14 – Documentação Técnica

🎯 Objetivos de Aprendizagem

  • Entender por que documentar é essencial (e não perda de tempo).
  • Conhecer os tipos de documentação (Técnica vs. Usuário).
  • Aprender a escrever um bom README.
  • Conhecer ferramentas como Markdown e Wikis.

📚 Conteúdo

1. "O código se documenta sozinho"? (Mentira!)

Um código limpo ajuda, mas ele não explica o PORQUÊ das decisões, nem como instalar o projeto. - Documentação é amor ao seu "eu" do futuro e aos colegas.

2. Tipos de Documentação

Para Usuário Final

  • Manuais, Tutoriais, FAQ.
  • Linguagem simples, sem jargão técnico.

Para Desenvolvedores (Técnica)

  • README: A capa do projeto. O que é? Como instala?
  • Wiki/Docs Internos: Arquitetura, padrões, decisões.
  • API Docs: Swagger/OpenAPI (como integrar).
  • Comentários no Código: Usar com moderação (explicar o porquê, não o o quê).

3. O Poder do Markdown

Markdown (o formato .md que estamos usando agora) é o padrão da indústria. Simples, legível e converte para HTML. - Títulos com # - Listas com - - Código com crases `

4. Como escrever um bom README

Um README deve responder em 5 segundos: 1. O que esse projeto faz? 2. Como eu rodo ele na minha máquina? 3. Quais tecnologias usa?

📅 Atividades