Pular para conteúdo

Aula 03: Organização e Boas Práticas 📂

Construindo Documentação de Elite 🏗️

O que vamos aprender hoje? 🎯

  1. Estrutura Modular 🧱
  2. Navegação Relativa 🔗
  3. README Profissional 🐙
  4. Destaques (Admonitions) 💡
  5. Padrões de Mercado 🌟

1. Estrutura Modular 🧱

Um arquivo gigante é difícil de manter.

Dividir para conquistar!

Crie uma estrutura lógica de pastas e arquivos.

Exemplo de Estrutura 📂

$ ls docs/
intro.md
guia-instalacao.md
faq.md

Isso facilita a busca e a leitura.

2. Navegação Relativa 🔗

Como ligar as peças do quebra-cabeça?

  • Mesma pasta: [Link](arquivo.md)
  • Pasta pai: [Link](../../README.md)
  • Subpasta: [Link](pasta/arquivo.md)

Deseja pular para o final?

Sintaxe: [Ir para Contato](#contato)

Cria uma navegação interna super ágil!

3. O README Profissional 🐙

É o seu "cartão de visitas" técnico.

O que não pode faltar?

Anatomia de um README 📍

  1. Título & Badges
  2. Descrição Visual (Capturas de tela)
  3. Quick Start (Como rodar agora?)
  4. Checklist de Progresso

Badges (Selo de Qualidade) 🎖️

Pequenos indicadores visuais úteis.

![Status](https://img.shields.io/badge/Status-Pronto-green)

Gera confiança imediata no usuário.

4. Destaques (Admonitions) 💡

Atraia o olhar para o que importa.

Dica

Markdown é vida!

!!! info "Nota" Informação relevante aqui.

Tipos de Alertas 🚨

  • !!! note (Azul)
  • !!! tip (Verde)
  • !!! warning (Laranja)
  • !!! danger (Vermelho)

Emojis: Use com Moderação 😊

Eles ajudam na quebra de blocos de texto.

Mas... não vire um chat de figurinhas! 🚫

Mantenha o tom profissional.

Estrutura do Site (Mermaid) 🧜‍♀️

mermaid graph TD A[index.md] --> B[Introdução] A --> C[Configuração] C --> D[Variáveis de Ambiente] A --> E[Referência API]

5. Padrões de Mercado 🌟

  • Keep It Simple: Linguagem clara.
  • Consistency: Use os mesmos termos sempre.
  • Accessibility: Legendas em todas as imagens.

Praticando no Terminal 🐚

$ mkdir docs
$ touch docs/index.md
$ echo "## Bem-vindo" > docs/index.md

Exercício Rápido 🧠

Como volto um nível de pasta no Markdown?

A) /.. B) ../ ✅ C) --back

Mini-Projeto 🎨

Crie sua pasta docs/.

  • Link README -> docs/index
  • Link docs/index -> docs/anotacoes
  • Use Checklists no README!

Resumo da Aula 📝

  • Divida o conteúdo em arquivos lógicos.
  • Use caminhos relativos para interligar.
  • Capriche no README com Badges e Alertas.

Próxima Parada... 🚂

Aula 04 - Markdown para Programação 💻

Blocos de código, destaque de sintaxe e documentação de APIs.

Obrigado! 🙏

"Sua documentação é a interface do seu código."

Ver Aula 04