ガイド作成ガイドライン
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文でまとめ、問題があればサポートチームへの案内をします。
H2のメインセクション内で内容をさらに整理するためにH3見出しを使うことを推奨します。上記のメイントピックの例が参考になります。
H4見出しも使えます。これはガイドの右側の目次に表示されず、H3のさらに細かい分割に便利です。
サブ見出しを使う場合は、親見出し内に2つ以上の同レベルのサブ見出しがあるのが一般的です。1つだけだと不自然なので避けてください。
今後、Markdownのテンプレートを用意し、新規ページ作成のスタートポイントとして提供予定です。お楽しみに。
タイトル
ガイドのタイトルは短く、ガイドの目的に基づいたものにしてください。読者がガイドを終えたときに何を達成できるかを意識しましょう。例えば、ソフトウェアのインストールや特定のトピックの情報提供などです。
タイトルの先頭には、ガイドが属する製品カテゴリを付けてください。これはサイドバーの配置と一致させるためです。同じセクションの他のガイドを見て、プレフィックスを確認しましょう。
VPS関連のガイドの良い例は：VPS: SteamCMD Linuxセットアップ
導入
導入は簡潔に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内に同様の情報がない場合や、技術知識を深めるための補足情報として有益な場合のみ使いましょう。競合他社のドキュメントへのリンクは避けてください。
フレンドリーでフォーマルかつ包括的に
ドキュメントは誰にでも親しみやすく、かつフォーマルなトーンを保ちます。経験や言語の壁を問わず、すべての読者に受け入れられる文章を心がけてください。
ガイドは読者が結果を出せるようにサポートするため、二人称（「あなたは〜する」）を使い、読者に焦点を当ててください。主観的な一人称（「私は〜と思う」）は避けましょう。
また、年齢、人種、性別、経験、国籍、宗教、政治的立場、性的指向、社会経済的地位、技術選択などに関わらず、誰でも受け入れられる内容にしてください。攻撃的な表現や差別的な内容は絶対に避けてください。
フォーマット
当ドキュメントはMarkdownで書かれており、広く使われているシンプルなマークアップ言語です。以下のセクションで使い方を説明します。
Markdownの詳細な使い方はMarkdown Guideを参照してください。
見出し
見出しはページを論理的に分割する重要なフォーマットです。メインタイトルはH1ですが、本文中で使うことはなく、ファイル上部のtitleメタデータで設定します。
ガイド内ではH2をメインセクションに使い、H3でサブセクションに分けます。例えば、複数のステップに分けて説明する場合などです。H4も使えますが、あまり多用しません。H4は目次に表示されません。
サブ見出し（H3など）を使う場合は、同じレベルの見出しが2つ以上あることを確認してください。1つだけだと誤用です。
見出しの例：
## インストール
H2 - メインセクション
### ゲームファイルのダウンロード
H3 - H2のサブセクション
#### SteamCMD経由
H4 - H3のサブセクション
#### GitHubから手動で
H4 - H3のサブセクション
### 設定の準備
H3 - H2のサブセクション
### サーバーの起動
H3 - H2のサブセクション
インラインMarkdown
読みやすさ向上のため、様々なインラインフォーマットを使います。
太字
重要な情報の強調に使います。例：
- ステップの切り替え
- ホスト名、認証情報、ユーザー名
- 重要用語
**hello there** → hello there
イタリック
新しい技術用語の紹介に使います。例：
- リバースプロキシを設定します。
*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] |
コードブロック
コマンドやスクリプト、ターミナル出力などの表示に便利です。
コードブロックはバッククォート3つで囲み、言語指定も可能です。例（JavaScript）：
function hello(name) {
console.log(name)
}
var server = "ZAP-Hosting"
hello(server)
注意書き（アドモニション）
特定の情報を強調するために5種類の注意書きを使えます。書き方は同じで、キーワードを変えます。
例：
:::note
これはメモです！キーワードを変えて種類を変えられます。
:::
Note（メモ）
重要ではないが役立つ補足情報に使います。
Tip（ヒント）
経験に基づくヒントを入れます。
Info（情報）
ユーザーに知ってほしい重要情報に使います。
Caution（注意）
ユーザーが注意すべき点を強調します。
Danger（危険）
重大なバグや非推奨機能など、特に注意が必要な情報に使います。
スクリーンショット
視覚的に手順を案内するのにスクリーンショットは非常に有効です。適切な場所で使いましょう。
スクリーンショット内の文字はすべて英語にしてください。ドキュメントは英語で書かれており、他言語版でも同じ英語画像を使うためです。
解像度は十分に高く、すべての要素が読みやすいことが重要です。小さすぎたりトリミングが激しい画像は避けてください。
画像の挿入例：
Imgurなどの画像アップロードサイトを使うか、GitHubの編集画面に直接ドラッグ＆ドロップすると自動アップロードされます。
用語
ドキュメント全体で使う重要用語を統一します。すべて米国英語のスペルを使い、一貫性を保ちます。
ZAP-Hosting製品名
ZAP-Hosting製品を言及する際は、正しい名称、スペル、大文字小文字を必ず守ってください。製品サイト（ZAP-Hosting公式サイト）での表記を確認しましょう。
ユーザー定義属性
多くのガイドで、ユーザーが自分の情報を入力する必要がある設定項目（ユーザー名、ホスト名、ドメイン、IPアドレス、URLなど）があります。
これらは[your_attribute]の形式で表記し、attributeは属性名に置き換えます。例：
- IPアドレスの場合：
[your_server_ip] - URLの場合：
http://[your_server_ip]:30120
読者が自分の環境に合わせて変更すべき部分であることを明確に示します。初出時に説明や注意書きを入れて理解を促してください。
ホスト名、ユーザー名、データベース名のデフォルトはzaphostingを使います。
ソフトウェア名
ソフトウェア名は正しいスペルと大文字小文字を守ってください。公式サイトの表記に合わせるのが基本です。
初出時には公式サイトへのリンクを貼りましょう。