Écrire des guides

Créer un fichier de guide

Pour commencer à écrire un guide, vous devez créer un fichier avec l'extension .mdx. Vous devez créer ce fichier dans le répertoire /content/docs/en, après tout dépend dans quelle section vous voulez faire le guide, donc vous pouvez décider dans quel sous-dossier vous devriez le mettre.

Supposons que je veux faire un guide sur les bases de Java, je le mettrais dans /content/docs/en/guides/java-basics. Vous aurez à fouiller un peu pour trouver où vous voulez le mettre.

Avant-propos

L'avant-propos sont les métadonnées de votre guide, cela indique à notre site web comment afficher votre guide. Il doit être placé au tout début du fichier, et commence avec --- et se finit par ---.

Voici un exemple :

---
title: "Java Basics"
description: "Learn the basics of Java programming."
authors:
    - name: "Your Name"
      url: "https://yourwebsite.com"
icon: YourIcon 
---

Comme vous pouvez le voir, c'est assez intuitif, vous avez juste besoin de remplir les détails pour votre guide. Si vous n'avez pas d'URL à laquelle vous voulez vous rattacher, n'écrivez juste pas cette ligne. De plus, la section auteurs est optionnelle, donc si vous ne voulez pas l'ajouter, vous pouvez juste l'omettre, même si nous vous encourageons à le faire et à vous créditer.

L'indentation dans l'avant-propos est important, donc soyez sûrs de le faire comme dans l'exemple.

Structure du contenu

Vous devriez structurer le contenu de votre guide de manière claire et organisée. Voici quelques astuces pour le faire :

• Introduction : Commencez avec un aperçu du sujet et ce que le lecteur peut espérer apprendre.
• Prérequis : Listez tous les prérequis ou les connaissances préalables que le lecteur doit avoir avant de plonger dans le guide.
• Instructions pas-à-pas : Divisez le contenu en étapes claires et concrètes. Utilisez les titres et sous-titres pour organiser les informations.
• Exemples de code : Incluez des extraits de code pour illustrer les points clés. Soyez sûr d'expliquer chaque exemple rigoureusement.
• Conclusion : Résumez les points importants et encouragez le lecteur à explorer plus loin ou essayer ce qu'ils ont appris.

Maintenant, si vous rédigez une section vraiment importante, vous devriez la diviser en plusieurs pages afin de faciliter la lecture et la compréhension pour le lecteur. Personne n'a envie de lire un gros bloc de texte d'un seul coup !

Lorsque nous rédigeons des guides, nous devrions aussi réfléchir à la manière dont les lecteurs vont les consulter, car beaucoup de personne préfèrent parcourir le contenu plutôt que de le lire en détail. C'est pourquoi il est préférable de répartir l'information sur plusieurs pages, afin qu'elle paraisse moins volumineuse pour le lecteur. Pensez également à utiliser des listes à puces, des listes numérotées et d'autres techniques de mise en forme afin de rendre le contenu plus facile à parcourir.

Mise en forme

Nous utilisons Markdown pour la mise en forme de nos guides. Voici quelques points clés à garder à l'esprit :

• Utilisez les en-têtes (#, ##, ###) pour organiser votre contenu.
• Utilisez des listes à puces et des listes numérotées pour plus de clarté.
• Utilisez les blocs (```) pour les extraits de code
• Utilisez des liens pour référencer d'autres guides ou ressources externes.

Il s’agit du même type de mise en forme que vous verrez sur la plupart des sites de documentation, ainsi que sur des plateformes de médias sociaux comme Discord.

Links

Everyone knows what a link is. However, there is a difference between linking to an external resource and linking to an internal one.

In general, in Markdown they are written like this: [Your Text](Your link)

External

Nothing to explain, just https://example.com.

Internal

You cannot use regular links here. Let's say your link to another guide is https://hytalemodding.dev/en/docs/quick-start. You can't write it like that because you are not only referring to the page but also to the language, which is not correct. Instead, type ./quick-start which is correct and links to the page in the user's language.

Accessing files

• Current Folder: ./
• Folder above: ../ as many times as this folder is higher in the hierarchy.

Icons

If you want to add an icon for your page then you should use Lucide.

1. Go to the site and find an icon you like.
2. Once you have selected an icon, click on it, then click "See in action"
3. Next, click on "React" which we are using. You will only need the text in the curly brackets on the first line.
4. Next, simply paste icon: YourIcon into Frontmatter.

Callout

Vous pouvez également créer un "Callout" pour mettre en avant des informations importantes ou des conseils. Utilisez la syntaxe suivante :

<Callout>
    Ceci est un message de callout.
</Callout>

Vous pouvez changer la couleur du callout en ajoutant un attribut type. Par exemple :

<Callout type="info">
    Ceci est un callout d'information.
</Callout>

Les types disponibles sont : info, warning, error, et success.

Difficulty levels

These are types of callouts, they are optional, they show how complex your page can be. There are 3 main levels of complexity.

Their usage is the same as in callout, but we would advise not to change the title. Inside, you write why your page is classified as this level and what the user should know.

Conclusion

C'est tout! Vous êtes maintenant un maître dans la rédaction de guides. Rappelez-vous, ne pensez pas que vous devez être parfait avec votre anglais, écrivez le guide de la manière dont vous expliquerez le sujet à quelqu'un, et n'hésitez pas à demander des commentaires ou de l'aide si vous en avez besoin.

Bonne écriture !