Escrevendo guias

Criando um arquivo de guia

Para começar a escrever um guia, crie um arquivo com a extensão .mdx. Crie esse arquivo dentro do diretório /content/docs/en. O local exato dependerá da seção onde deseja incluir o guia. Por isso, escolha a pasta apropriada após esse caminho.

Suponha que eu queira criar um guia de fundamentos do Java, então eu o colocaria em /content/docs/en/guides/java-basics. Você precisará investigar um pouco para descobrir onde deseja colocá-lo.

Frontmatter

O frontmatter representa os metadados do seu guia. Ele informa ao nosso site como o conteúdo deve ser mostrado. Isso precisa estar no topo do arquivo, que começa com --- e termina com ---.

Veja um exemplo abaixo:

---
title: "Fundamentos do Java"
description: "Aprenda os conceitos básicos de programação em Java."
authors:
    - name: "Seu nome"
      url: "https://seusite.com"
---

Como você pode ver, é bastante autoexplicativo. Basta preencher os detalhes para o seu guia específico. Caso não tenha uma URL para pôr naquele espaço, deixe-o em branco. A seção de autores é opcional. Se preferir, você pode omiti-la, mas recomendamos que a utilize para se identificar como autor do guia para obter os devidos créditos.

A indentação no frontmatter é fundamental. Garanta que os espaços estejam exatamente como no exemplo.

Estrutura do conteúdo

Você deve estruturar o conteúdo do seu guia com clareza e organização. Veja abaixo algumas dicas de como fazer isso:

• Introdução: comece com uma visão geral do tópico e o que o leitor pode esperar aprender;
• Pré-requisitos: liste quaisquer pré-requisitos ou conhecimentos prévios que o leitor deva ter antes de se aprofundar no guia;
• Etapas das instruções: divida o conteúdo em etapas claras e objetivas. Use títulos e subtítulos para organizar as informações;
• Exemplos de código: inclua trechos de código para ilustrar os principais pontos. Certifique-se de explicar cada exemplo de forma detalhada;
• Conclusão: resuma os principais pontos e incentive o leitor a explorar mais ou a colocar em prática o que aprendeu.

Se você estiver escrevendo uma seção muito extensa, o ideal é dividi-la em várias páginas para que a informação seja mais fácil de ser entendida. Ninguém quer ler um enorme bloco de texto de uma só vez!

Ao escrever guias, devemos pensar em como as pessoas os consumirão e muitas preferem passar rapidamente pelo conteúdo em vez de lê-lo em detalhes. É por isso que é melhor dividir a informação em várias páginas, para que o conteúdo pareça menos denso para o leitor. Além disso, considere usar tópicos, listas numeradas e outras técnicas de formatação para tornar o conteúdo mais amigável.

Formatação

Utilizamos Markdown para formatar os nossos guias. A seguir estão alguns pontos importantes a serem considerados:

• Use títulos (#, ##, ###) para organizar o seu conteúdo;
• Use listas com marcadores e listas numeradas para maior clareza;
• Use blocos de código (```) para trechos de código;
• Use links para referenciar outros guias ou recursos externos.

Esse é o mesmo tipo de formatação que você verá na maioria dos sites de documentação e também em plataformas sociais, como o Discord.

Você também pode usar um callout para destacar informações ou dicas importantes. Use a seguinte sintaxe:

<Callout>
    Esta é uma mensagem em destaque de callout.
</Callout>

Você pode alterar a cor do callout adicionando um atributo type. Por exemplo:

<Callout type="info">
    Isto é um callout de informação
</Callout>

Os tipos disponíveis são: info, warning, error e success.

Conclusão

Isso é tudo! Agora você é um mestre em escrever guias. Não se preocupe em ter um inglês perfeito. Escreva o guia como se estivesse explicando o assunto para alguém e não hesite em pedir feedback ou ajuda se precisar.

Boa escrita!