Escrevendo guias

Criando um arquivo de guia

Para começar a escrever um guia, crie um arquivo com a extensão .mdx. Você precisa criar esse arquivo dentro do diretório /content/docs/en. A partir disso, tudo depende da seção em que você deseja criar o guia, pois assim poderá decidir em qual pasta colocá-lo.

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

Frontmatter

O frontmatter é os metadados do seu guia; ele informa ao nosso site como exibir o seu guia. Isso precisa estar no topo do arquivo, que começa com --- e termina com ---.

Aqui está um exemplo:

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

Como você pode ver, é bastante autoexplicativo; basta preencher os detalhes do seu guia específico. Se você não tiver uma URL para vincular a si mesmo, basta não escrever essa linha. Além disso, a seção de autores é opcional; portanto, se você não quiser adicioná-la, pode simplesmente deixá-la de fora, embora recomendemos que a inclua e dê o devido crédito a si mesmo.

A indentação no frontmatter é importante; portanto, certifique-se de mantê-la consistente com o exemplo.

Estrutura do Conteúdo

Você deve estruturar o conteúdo do seu guia de forma clara e organizada. Aqui estão 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.
• Instruções passo a passo: 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 pontos principais. Certifique-se de explicar cada exemplo de forma detalhada.
• Conclusão: Resuma os pontos principais e incentive o leitor a explorar mais ou a colocar em prática o que aprendeu.

Agora, se você estiver escrevendo uma seção realmente grande, deve dividi-la em várias páginas para facilitar a assimilação das informações pelo leitor. Ninguém quer ler um grande bloco de texto de uma só vez!

Ao escrever guias, devemos pensar em como as pessoas irão consumi-los; muitas preferem percorrer o conteúdo rapidamente em vez de lê-lo em detalhes. Por isso, é melhor dividir as informações em várias páginas, para que pareçam uma quantidade menor de conteúdo para o leitor. Além disso, considere usar listas com marcadores, listas numeradas e outras técnicas de formatação para tornar o conteúdo mais fácil de escanear.

Formatação

Utilizamos Markdown para formatar nossos guias. Aqui estão alguns pontos-chave a serem considerados:

• Use títulos (#, ##, ###) para organizar o 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 de mídia social, 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 usando callout.
</Callout>

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

<Callout type="info">
    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. Lembre-se apenas de que você não precisa ser perfeito no inglês; escreva o guia da mesma forma que explicaria o assunto a alguém e não hesite em pedir feedback ou ajuda caso precise.

Boa escrita!