É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 cela 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 fini par ---.

Voici un exemple :

---
title: "Bases de Java"
description: "Apprenez les bases de la programmation Java."
authors:
    - name: "Votre nom"
      url: "https://votresiteweb.com"
---

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 devez 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
• Utiliser 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.

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'.

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 !