Skip to main content

ガイド作成ガイドライン

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セットアップ

導入

導入は簡潔に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のドキュメントチームも内容を確認し、必要に応じて修正や改善を提案します。

Hint

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

実用的かつ役立つ内容に

読者が記事を読み終えた時に、何かを学び、作り、設定できることが重要です。どんな経験レベルの読者にも対応できるよう、トピックを徹底的に掘り下げ、必要な前提条件もすべてカバーしてください。外部サイトへのリンクは、ZAP-Docs内に同様の情報がない場合や、技術知識を深めるための補足情報としてのみ使い、競合他社のドキュメントへはリンクしないでください。

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

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

ガイドは読者の教育と成果達成を目的としているため、文章は二人称(例:「あなたは〜する必要があります」)で書き、読者に直接語りかける形にしてください。主語を一人称(例:「私は〜と思います」)にしないでください。

また、年齢、人種、性別、経験、国籍、宗教、政治的立場、性的指向、社会経済的背景、技術選択などに関わらず誰でも受け入れられる内容にしてください。差別的・攻撃的な表現は避けてください。

フォーマット

当社のドキュメントはMarkdown記法で書かれており、広く使われていて比較的簡単です。以下のセクションで使い方を説明します。

Hint

Markdownの詳細な説明や例はMarkdown Guideを参照してください。

見出し

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

ガイド本文ではH2をメインセクションの区切りに使い、H3でサブセクションに分けます。例えば大きなセクションを複数のステップに分ける場合などです。H4も使えますが、あまり多用せず、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
  • キーバインド:ENTERCTRL + 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(危険)

危険タイトル(任意)

重大な注意事項や既知のバグ、非推奨機能の警告に使います。

スクリーンショット

視覚的に手順を案内するのにスクリーンショットは非常に有効です。適宜使うことを推奨します。

ドイツ語版対応のため、スクリーンショットは英語版とドイツ語版の両方を用意してください。ガイド内で並べて配置し、ドイツ語版はZAP-Docsチームが翻訳後に差し替えます。

画像追加は以下のようにURLを指定します:

![](your_url)

画像はImgurなどの外部サービスにアップロードするか、GitHubの編集画面に直接ドラッグ&ドロップして自動アップロードしてください。

用語

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

ZAP-Hosting製品名

ZAP-Hosting製品を言及する際は、正しい名称、スペル、大文字小文字を必ず守ってください。製品サイト(ZAP-Hosting公式サイト)で確認できます。

ユーザー定義属性

ユーザーが自分の環境に合わせて置き換える必要がある設定(ユーザー名、ホスト名、ドメイン、IPアドレス、URLなど)は、[your_attribute]の形式で表記してください。attributeは属性名に置き換えます。

例:IPアドレスなら[your_server_ip]、URLならhttp://[your_server_ip]:30120のようにします。読者がどこを変更すべきか最初に説明を入れてください。

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

ソフトウェア名

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

ソフトウェアを初めて言及する際は、公式サイトへのリンクを貼ってください。