Markdown e documentação técnica básica

Nível: A2

Objetivo

Ler e escrever documentação técnica curta em Markdown: títulos, listas, blocos de código, links e notas, montando um README básico com seções install, usage, examples e troubleshooting.

Explicação

Markdown é uma forma simples de escrever texto formatado em arquivos `.md`. Em projetos de software, o arquivo principal se chama `README.md` e explica o que o projeto faz, como instalá-lo e como usá-lo. A extensão `.md` significa 'markdown'.

Headings (títulos): use `#` para o título principal e `##` para subtítulos. Mais `#` significam títulos menores na hierarquia visual.

• `# Project Name` → título principal
• `## Install` → subtítulo
• `### Step 1` → sub-subtítulo

Sempre coloque um espaço depois do `#`. Sem espaço, o texto continua sendo parágrafo comum.

Lists (listas): use `-` ou `*` para listas com marcadores (bullet points) e `1.`, `2.` para listas numeradas. Use listas numeradas quando a ordem importa (passos de instalação) e listas com marcadores quando a ordem não importa (recursos do projeto).

Code blocks (blocos de código): três crases consecutivas em uma linha delimitam comandos e saídas. O texto entre as crases aparece em fonte monoespaçada, ideal para comandos como `npm install` ou `pip install requests`. Você também pode indicar a linguagem logo após as crases, por exemplo `bash` ou `python`, para destacar a sintaxe.

Para código inline, use uma única crase: `install` aparece em fonte de código inline. É útil para destacar nomes de comandos ou arquivos como `README.md`.

Links: use `[texto visível](https://endereço)` para criar links clicáveis. O texto entre colchetes é o que o leitor vê; o endereço entre parênteses é o destino.

Notes (ênfase e avisos): use `*itálico*` para destacar termos e `negrito` para avisos importantes. Use também `>` no começo de uma linha para criar uma citação ou aviso em destaque.

Em um README típico, organize as seções nesta ordem:

1. `Description`
2. `Install`
3. `Usage`
4. `Examples`
5. `Troubleshooting`

A ordem pode variar, mas `Install` geralmente vem antes de `Usage`, e `Troubleshooting` resolve dúvidas comuns no final.

Exemplos

Erros comuns

• Esquecer o espaço depois do #: `#Install` aparece como texto comum; o correto é `# Install`.
• Confundir # com bullet de lista: `# Item` não é um item de lista; use `- Item`.
• Misturar listas numeradas e com marcadores sem necessidade: se a ordem importa, use números; se não importa, use `-`.
• Esquecer as três crases de fechamento do bloco de código: sem elas, o resto do arquivo vira código.
• Esquecer os parênteses em links: `[text]https://...` não vira link; use `[text](https://...)`.
• Colocar cabeçalhos fora de ordem: usar `### Install` quando o pai `## Setup` não existe quebra a hierarquia visual.

Prática guiada

Converta este texto simples em Markdown:

Texto simples:

• Título: My Project
• Subtítulo: Install
• Comando: `pip install my-project`
• Subtítulo: Usage
• Comando: `my-project run`
• Link com texto 'docs' para https://example.com/docs

Resultado em Markdown:

Use um único `#` para o título principal `My Project`. Use dois `##` para os subtítulos `Install` e `Usage`. Coloque cada comando entre crases simples para inline code, ou entre três crases para um bloco de código. Use o formato `[texto](url)` para o link.

O README final começa com `# My Project`, segue com `## Install` e o comando `pip install my-project`, depois `## Usage` com `my-project run`, e termina com `See the [docs](https://example.com/docs) for more details.`. Observe como cada `#` indica um nível e o link usa colchetes seguidos de parênteses.

Resumo

Markdown usa `#` para títulos, `-` ou números para listas, três crases para blocos de código, `[texto](url)` para links e `>` para avisos. Um README típico tem seções Description, Install, Usage, Examples e Troubleshooting, nessa ordem.

História: Markdown e documentação técnica básica

Nível: A2

História em inglês

Updating the README

On Monday morning, Anna opened the repository for a small CLI tool called quicknote. The README only had a title and one short paragraph. She decided to add four sections: Description, Install, Usage, and Troubleshooting. For the main heading, she used a single hash followed by the project name. For the Install section, she wrote the command inside a code block.

A small Markdown mistake

Her teammate Lucas opened the file and noticed a small mistake. The code block didn't have the closing triple backticks, so the rest of the file looked like code. Anna added the closing backticks on a new line and saved the file. She also added a link to the official guide at the end of the Usage section. Lucas suggested a short note for users who run an older version of Node.

Adding a troubleshooting section

On Tuesday, a user reported an installation error on Windows. Anna created a new Troubleshooting section and added the common error message. She wrote the fix as a numbered list with three steps. Finally, she asked Lucas to review the whole README one more time. Lucas approved the change, and the tool was ready for the next release.

Tradução linha por linha

Notas de vocabulário

• repository = repositório; pasta do projeto com histórico de alterações
• README = arquivo principal de documentação do projeto
• section = seção; bloco temático dentro do README
• code block = bloco de código delimitado por três crases
• closing triple backticks = as três crases de fechamento do bloco de código
• link = atalho clicável; usa [texto](url) em Markdown
• Troubleshooting = seção que lista erros comuns e suas soluções
• numbered list = lista numerada; usa 1., 2., 3.
• review = revisão; leitura crítica antes de aprovar uma alteração
• release = lançamento; nova versão publicada do projeto

Perguntas de compreensão

1. What tool was Anna updating the README for?
2. What four sections did Anna add to the README?
3. What mistake did Lucas find in the code block?
4. How did Anna fix the code block?
5. What kind of note did Lucas suggest?
6. Why did Anna create the Troubleshooting section?
7. How did Anna write the fix in the Troubleshooting section?
8. Who reviewed the README at the end of the story?

Prática com a história

1. Converta para Markdown: Subtítulo Usage
2. Escreva um link com texto docs para https://example.com/docs.
3. Como você abre um bloco de código em Markdown?
4. Reescreva como item de lista: Run npm install
5. Crie um aviso em destaque com o texto: requires Node 18+.