ガイドの執筆

ガイドファイルの作成

ガイドの作成を始めるには、.mdx拡張子のファイルを作成し、 ガイドの作成を始めるには、.mdx拡張子のファイルを作成し、 content/docs/enディレクトリ内に配置してください。どの記事にガイドを作成するかによって、フォルダの配置が決まってます。

もしJavaの基本的なガイドを作りたいなら、content/docs/en/guides/java-basicsに配置します。 既存のフォルダ構成から適切な場所を判断してください。 既存のフォルダ構成から適切な場所を判断してください。

前書き

前書きはガイドのメタデータで、Webサイトにガイドをどう表示するかを指示します。 これはファイルの一番上、'---'で挟まれている部分に記述する必要があります。 これはファイルの一番上、'---'で挟まれている部分に記述する必要があります。

例

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

ご覧の通りガイドの詳細を記述するだけでOKです。 リンクしたいURLが無い場合は、その行を削除してください。 authors（著者）の記載は任意ですが、明記することを推奨しています。

前書きの文法は例と同じフォーマットで揃えてください。

コンテンツ構造

ガイドの中身は、読み手が理解しやすいように整った構造にしてください。 そのためのヒントをいくつか紹介します。

• 導入：トピックの概要と読み手が何を学べるかを説明しましょう。
• 前提条件：ガイドを読み進める前に必要な環境や事前知識をリストアップしましょう。
• 段階的な指示：ガイドの内容を複数の手順として小分けにしましょう。 見出しと小見出しを使用して情報を整理します。
• コード例：重要なポイントを示すコードスニペットを入れてください。 それぞれの例を使用して、詳細に説明をするようにしましょう。
• 結論：要点をまとめ、読み手の学習意欲を出させるようにしましょう。

記事が大きくなりそうな場合は、複数のページに分けることで読み手も理解しやすくなります。 冗長な文章を好む人はほとんどいません。

ガイドを作成する際には、読み手がどのように利用するかを考慮する必要があります。多くの人は、内容を詳細に読むよりも、流し読みをしています。 そのため、情報を複数のページに分割し、読み手にとって情報がシンプルなように見せる方が効果的です。 また、箇条書き、番号付きリスト、その他の書式設定の手法を活用して、読みやすくすることも考えてみてください。

書式設定

ガイドの書式設定にはMarkdownを使用しています。 以下に留意すべきポイントをいくつか紹介します。 以下に留意すべきポイントをいくつか紹介します。

• 見出し (#, ##, ###) を使用して内容を整理できます。
• 箇条書きと番号付きリストを使用するとわかりやすくなります。
• コードスニペットにはコードブロック (```) を使用できます。
• リンクを添付して、他のガイドや外部リソースを参照できます。

これらは、ほとんどのドキュメントサイトや、Discord などのSNSプラットフォームでよく使われる書式です。

重要な情報やヒントを強調するために、吹き出しを作成することもできます。 以下の構文を使用してください。

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

属性typeを追加することで、吹き出しの色を変更できます 例 例

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

利用可能なtypeは次のとおりです。info warning error success

終わりに

これで完了です！ あなたはすでにガイド作成のプロです。 これで完了です！ あなたはすでにガイド作成のプロです。 完璧な英語である必要はありません。誰かに説明するようなイメージでガイドを書いてください。必要であればフェードバックや助けを求めることもできます。

楽しい執筆ライフを！