Das Schreiben eines Leitfadens

Das Erstellen von einer Leitfadendatei

Um mit dem Schreiben eines Leitfadens zu beginnen, ist das Anlegen einer Datei mit der Endung ".mdx" notwendig. You need to create this file inside the /content/docs/en directory, now it depends in which section you want to make the guide, so you can decide which folder you should put it in after that.

Nehmen wir an, Sie wollen ein Leitfaden über die Grundkenntnisse von Java schreiben; Sie würden diesen in /content/docs/en/guides/java-basics einfügen Sie werden ein wenig stöbern müssen, um die Wahl zu treffen, wo genau sie ihn platzieren wollen.

Dateikopf

Der Dateikopf ist der Metadatenblock, er informiert unsere Website, auf welche Weise sie den Leitfaden, welchen Sie erstellt haben, anzeigen soll. This needs to be at the very top of the file, which starts with --- and ends with ---.

Here's an example:

Now as you can see, it's pretty self explanatory, you just need to fill in the details for your specific guide. If you don't have a URL you want to link yourself to, just don't write that whole line. Des Weiteren ist der Autorenbereich optional; sollte das Hinzufügen von diesem für Sie nicht infrage kommen, können sie diesen einfach auslassen, obwohl wir Sie ermutigen dies nicht zu tun, und sich selbst als Urheber angeben.

The indentation in the frontmatter is important, so make sure to keep it consistent with the example.

Content Structure

You should structure the content of your guide in a clear and organized manner. Here are some tips on how to do that:

• Introduction: Start with an overview of the topic and what the reader can expect to learn.
• Prerequisites: List any prerequisites or prior knowledge the reader should have before diving into the guide.
• Step-by-Step Instructions: Break down the content into clear, actionable steps. Use headings and subheadings to organize the information.
• Code Examples: Include code snippets to illustrate key points. Make sure to explain each example thoroughly.
• Conclusion: Summarize the main points and encourage the reader to explore further or try out what they've learned.

Now if you're writing a really big section, you should split this into multiple pages so that it's easier for the reader to digest the information. No one wants to read a big wall of text all at once!

When we write guides, we should also think of how people will consume them, and many people prefer to skim content rather than read it in detail. This is why it's better to split information into multiple pages, so it looks like a smaller amount of information to the reader. Also, consider using bullet points, numbered lists, and other formatting techniques to make the content more scannable.

Formatting

We use Markdown for formatting our guides. Here are some key points to keep in mind:

• Use headings (#, ##, ###) to organize your content.
• Use bullet points and numbered lists for clarity.
• Use code blocks (```) for code snippets.
• Use links to reference other guides or external resources.

This is the same type of formatting you'll see on most documentation websites, and also social media platforms like Discord.

You can also make a Callout to highlight important information or tips. Use the following syntax:

<Callout>
    This is a callout message.
</Callout>

You can change the color of the callout by adding a type attribute. For example:

<Callout type="info">
    This is an info callout.
</Callout>

Available types are: info, warning, error, and success.

Conclusion

That's all! You are now a master at writing guides. Just remember, do not think you need to be perfect with your English, write the guide the way you will explain the topic to someone, and don't hesitate to ask for feedback or help if you need it.

Happy writing!