メインコンテンツへスキップ

ガイド作成ガイドライン

Guides Banner

ZAP-Docsのコンテンツの品質とスタイルを常に一貫させるために、ドキュメントの作成や編集時に使用する一連のガイドラインを用意しています。あなたの提案や最終的なプルリクエストが迅速に処理されるように、これらのガイドラインを必ず厳守してください。何よりも、読者がガイドを読み進める際に、より良く一貫した高品質な体験を得られることを保証します。

ガイドの寄稿ガイドラインは以下のセクションに分かれています：

  • 構成
  • スタイル
  • フォーマット
  • 用語

コンテンツ作成を始める前に、これらのセクションを少なくとも一度は目を通すことをおすすめします。作成中に迷ったときに参照するのにも便利です。

構成​

ZAP-Docsのすべてのガイドは、短い導入文と前提条件や準備手順から始まり、メインコンテンツ、そして簡単な結論で締めくくるという比較的一貫した構成を持っています。

ガイドの種類によっては構成を変更することもあります。これは提案時にZAP-Docsチームと相談可能です。見出しの使い方はMarkdownの基本的な書き方で行います。

一般的に期待される構成は以下の見出しで構成されます：

  • ページタイトル (H1) - ページ上部の title メタデータで設定します。
  • 導入 (H2) - ガイドのテーマを簡潔に1～2文で説明し、何を達成するかを明示します。
  • 準備 (H2) - 任意の見出しです。ガイドを進める前に必要な前提条件や準備手順がある場合にのみ使用します。例えば、ユーザーがサーバーにログインする必要がある場合はSSH初期アクセスガイドへのリンクをここで紹介します。ソフトウェアやハードウェアの要件、ファイアウォールの設定方法などもここに含めます。ZAP-Docs内に関連ガイドがあればリンクを貼ることを推奨します。
  • メインテーマ (H2) - ガイドの最初のメインセクションです。多くの場合はインストールがここに該当し、プロセスの各段階を細分化したサブセクションが続きます。ただし、情報提供型のガイドなどでは異なるメインテーマになることもあります。
  • 任意: サブトピック1 (H3)
  • 任意: サブトピック2 (H3)
  • ...
  • 任意: 別のトピック (H2)
  • 結論 (H2) - ガイドの最後に、読者が何を達成したかを1～3文でまとめ、問題があればサポートチームへの案内をします。
サブ見出しの使い方（H3 & H4）

H2のメインセクション内でさらに内容を整理するためにH3見出しを使うことを推奨します。上記のメインテーマセクションの例が参考になります。

H4見出しも使用可能です。これはガイドの右側の目次に表示されず、H3のさらに細かい分割に便利です。

サブ見出しを使う場合、親見出し内に2つ以上の同レベルのサブ見出しがあるのが一般的です。1つだけだと不自然なので避けてください。

今後、Markdownのテンプレートを用意し、新規ページ作成の出発点として使えるようにする予定です。近日中に追加予定です。

タイトル​

タイトルは簡潔で、ガイドの主な目的が明確に伝わるものにしてください。読者がガイドを終えたときに何ができるようになるか（インストール完了、サービス設定、技術理解など）がすぐにわかるようにしましょう。

タイトルは必ず該当製品カテゴリのプレフィックスから始めてください。このプレフィックスはサイドバーの該当セクションと一致させます。同じカテゴリの既存ガイドを参考にして命名規則を統一しましょう。

例：VPS製品に関するガイドなら VPS: SteamCMD Linuxセットアップ のようにします。

複数製品に共通する一般的なガイド（例：VPSと専用サーバー両方で使えるゲームサーバーのインストールなど）は製品名をタイトルに含めません。製品非依存のガイドとして扱います。

導入​

導入は短く簡潔に、1～2文程度で書きます。ガイドのテーマを簡単に説明し、何を達成できるかを明示してください。

SteamCMDに関するガイドの理想的な導入例：

  • 1文目: SteamCMDはPalworldやEnshroudedなど多くのゲームの専用サーバーをインストールするために必要な必須ツールです。
  • 2文目: 本ガイドではLinuxサーバーへのSteamCMDの初期セットアップ手順を解説します。例ではUbuntuを使用しますが、他のディストリビューションでもほぼ同様です。

このように、ガイドの内容と最終目標を簡潔にまとめます。

準備​

準備セクションは、読者がガイドを進める前に満たすべき前提条件を明確にするのに役立ちます。ソフトウェアやハードウェアの要件、ファイアウォールの設定方法、SSHやRDPでのサーバーログイン案内などが含まれます。

ZAP-Docsサイトで関連する準備手順のガイドがないか検索し、あればリンクを貼って読者に先に参照してもらうことを強く推奨します。例えばSSH初期アクセスガイドなどです。

よくある前提条件例：

  • 必要なソフトウェア（Git、Node.js、Python、Dockerなど）
  • 基本知識を得るためのチュートリアル（他のZAP-Docsページ）
  • APIなどのユーザーアカウント
  • 必要な設定（DNS、SSLなど）

リバースプロキシの例：

リバースプロキシをセットアップするにはLinuxサーバーが必要で、接続できる状態である必要があります。接続方法がわからない場合は[SSH初期アクセス](vserver-linux-ssh.md)ガイドを参照してください。また、所有しているドメインへのアクセスも必要です。使用するサブドメインごとに、LinuxサーバーのIPアドレスを指す`A` DNSレコードを作成してください。

メインテーマ​

ここからがガイドのメイン部分です。H2、H3、H4見出しを使って適切に構成してください。大きなセクションはH2で分け、さらにH3やH4で細分化するのが一般的です。

特にソフトウェアのセットアップ系ガイドでは、インストールというH2見出しを使い、その下に複数のH3サブセクションを設けることが多いです。構成に迷ったら提案段階で相談してください。良い構成を一緒に考えます。

各セクションの冒頭と末尾には簡単な導入文や締めの文を入れて、読者に今何をしているか、次に何をするかを伝えると親切です。最後のメインセクションは結論に自然につながるので締め文は必須ではありません。

例：

  • 導入文: このセクションではソフトウェアの設定を行い、カスタマイズします。
  • 締め文: 設定が完了しファイルを保存したら、次のセクションで管理者アカウントを作成し、ソフトウェアを起動します。

常に二人称（「あなたは～する」）で書き、読者に寄り添う形で進めましょう。

結論​

最後にガイドの結論を書きます。1～3文で読者が何を達成したかをまとめ、関連する他のZAP-Docsガイドへのリンクや、問題があればサポートチームへの案内を入れましょう。

良い結論例：

これでLinuxサーバー上でソフトウェアのセットアップが完了しました！このセクションのLinuxサービスガイドもぜひご覧ください。

ご質問やサポートが必要な場合は、いつでもサポートチームにお問い合わせください。毎日対応しています！🙂

スタイル​

ZAP-Hostingのドキュメントは、高品質で実用的、かつ誰でもアクセスしやすいガイドを目指しています。幅広い経験レベルの読者をサポートできるように書いてください。

技術的かつ正確に​

記事は技術的に正確で最新の情報を反映している必要があります。読者が最終的な目標を達成できるだけでなく、過程で何をしているか理解できるように説明してください。各ステップには明確な目的と説明を入れ、必要に応じてオプションやフラグも紹介しましょう。読者に「なぜこの操作をするのか」を常に伝えることが大切です。

プルリクエスト前に必ずガイドを校正・テストし、技術的に正しく動作することを確認してください。ZAP-Hostingのドキュメントチームも内容をチェックし、必要に応じて改善点を提案します。

ヒント

プルリクエスト前にスペルチェックツールを使うことをおすすめします。便利なサイト：https://languagetool.org/

実用的かつ役立つ内容で​

読者が記事を読み終えたときに、何かを学び、構築し、セットアップできることが目標です。どんな経験レベルの読者にも対応できるよう、トピックを徹底的にカバーし、前提条件も含めて詳細に説明してください。外部サイトへのリンクは、ZAP-Docs内に該当ドキュメントがない場合や、技術知識を深めるための補足情報としてのみ使用してください。競合他社のドキュメントへのリンクは避けてください。

フレンドリーでフォーマルかつ包括的に​

ドキュメントは親しみやすく、誰でも読みやすいトーンを目指しますが、同時にフォーマルさも保ちます。読者の経験や言語の壁に関係なく受け入れられる文体にしてください。

ガイドは読者が結果を出せるようにサポートすることが目的なので、二人称（「あなたは～する」）を使い、読者に焦点を当ててください。主観的な一人称（「私は～と思う」）は避けましょう。

また、年齢、人種、性別、国籍、宗教、政治的立場、性的指向、社会経済的背景、技術選択などに関して差別的・攻撃的な表現は絶対に避けてください。ZAP-Hostingの行動規範に従ってください。

フォーマット​

当社のドキュメントはMarkdownで書かれており、広く使われているシンプルなマークアップ言語です。以下のセクションで使い方を説明します。

ヒント

Markdownの詳しい使い方はMarkdown Guideを参照してください。

見出し​

見出しはページを論理的に分割するための重要なフォーマットです。メインタイトルはH1ですが、本文中で使うことはなく、ページ上部の title メタデータで設定します。

ガイド内ではH2をメインセクションの区切りに使い、H3でサブセクションに分けます。例えば大きなセクションを複数のステップに分ける場合などです。H4も使えますが、目次には表示されません。

備考

サブ見出し（H3など）を使う場合は、同じレベルの見出しが2つ以上あることを確認してください。1つだけだと誤用です。

見出しの例：

## インストール
H2 - メインセクション

### ゲームファイルのダウンロード
H3 - H2のサブセクション

#### SteamCMD経由
H4 - H3のサブセクション

#### GitHubから手動で
H4 - H3のサブセクション

### 設定の準備
H3 - H2のサブセクション

### サーバーの起動
H3 - H2のサブセクション

インラインMarkdown​

読みやすさ向上のため、様々なインラインフォーマットを使います。

太字​

重要な情報の強調に使います。例：

  • ステップ間の文脈切り替え
  • ホスト名、認証情報、ユーザー名
  • 重要用語

**hello there** → hello there

斜体​

新しい技術用語の紹介に使います。例：

reverse proxy（リバースプロキシ）

*ZAP-Hosting - More POWER!* → ZAP-Hosting - More POWER!

インラインコード​

技術的な情報（URL、ファイルパス、コマンドなど）に使います。

例：

  • ファイル名やパス：C:/User/[your_name]/AppData....test.png
  • URL：https://zap-hosting.com
  • ポート番号：:30120
  • コマンド：ipconfig
  • SQLクエリ：SELECT * FROM servers
  • キーバインド：ENTERやCTRL + C

テーブル​

繰り返し情報を整理するのに便利です。例：

| コマンド    | 説明                     | 使い方                |
| ----------- | ------------------------ | --------------------- |
| /help       | ヘルプコマンドを送信     | /help [category]      |
| /stop       | サーバーを停止           | /stop [true/false]    |

コードブロック​

コマンドやスクリプト、ターミナル出力などを示すのに便利です。

コードブロックは ``` で囲み、言語指定も可能です。例（JavaScript）：

function hello(name) {
    console.log(name)
}

var server = "ZAP-Hosting"
hello(server)

注意書き（Admonitions）​

重要情報を強調するために使います。5種類あり、それぞれ目的が異なります。

タイトルは必ず明確に記述し、読者が内容の重要性をすぐ理解できるようにしてください。

書式は共通で、キーワードだけ変わります：

:::warning[タイトル]
	ここに内容を記述
:::

Note（補足）​

例：追加情報

読者の助けになるが必須ではない補足情報に使います。

Tip（ヒント）​

例：パフォーマンス最適化のヒント

実践的なアドバイスやベストプラクティスを共有する際に使います。

Info（重要情報）​

例：要件や重要な詳細

プロセスの前後で読者が知っておくべき重要な情報に使います。

Caution（注意）​

例：設定リスク

ガイドを進める際に起こりうる問題やミスを警告するために使います。

Danger（危険）​

例：既知のバグや非推奨機能

重大な警告（バグ、取り返しのつかない操作、セキュリティリスク、非推奨機能など）に使います。

スクリーンショット​

視覚的に手順を案内するのに非常に有効です。適切な箇所で積極的に使いましょう。

スクリーンショット内の表示は英語にしてください。ドキュメントは英語で書かれており、他言語版でも同じ英語画像を使うためです。

解像度は十分に高く、すべての要素が読みやすいことが重要です。小さすぎたりトリミングが激しい画像は避けてください。

画像挿入例：

![](your_url)

画像はImgurなどの外部サービスにアップロードしてURLを使うか、GitHubの編集画面に直接ドラッグ＆ドロップして自動アップロードする方法があります。

用語​

ドキュメント全体で使う重要用語を統一します。すべて米国英語のスペルを使い、一貫性を保ちます。

ZAP-Hosting製品名​

ZAP-Hosting製品を言及する際は、正しい名称、スペル、大文字小文字を必ず確認してください。ZAP-Hosting公式サイトの該当製品ページを参照してください。

ユーザー定義属性​

多くのガイドで、ユーザーが自分の情報を入力する必要がある設定項目（ユーザー名、ホスト名、ドメイン、IPアドレス、URLなど）があります。

静的な要素と区別するため、必ず [your_attribute] の形式で表記してください。attribute は属性名に置き換えます。

例：IPアドレスなら [your_server_ip]、URLなら http://[your_server_ip]:30120

読者がどの属性を変更すべきか、最初に説明や注釈を入れて理解を促してください。

ホスト名、ユーザー名、データベース名のデフォルトは zaphosting を使います。

ソフトウェア名​

ソフトウェア名は正しいスペルと大文字小文字を守ってください。公式サイトの表記に従い、記事内では一貫性を保ちます。

初出時には公式サイトへのリンクを貼ってください。

クッキー設定