Unraid Docs スタイルガイド
Unraid OS は LimeTech チームと Unraid コミュニティによって形作られています。私たちのドキュメントは、包括的で、正確で、最新であることを目指しています。ユーザーは世界中のさまざまな背景を持っているため、このガイドは Unraid ドキュメント全体で一貫性があり、明確な文章を書くための基盤を示します。
記述規則
スタイルとトーン
私たちのトーンは、親しみやすさと形式的な表現のバランスを取り、ユーザーが共感しやすい、詳細で正確な内容を目指します。
- 操作が固定されており、逸脱の余地がない場合は、形式的で直接的な指示を使用します。
- 文脈やシナリオを示す場合は、より親しみやすい内容にするため、会話的で説明的なトーンを使用します。
寄稿者として、トーンを選ぶ際は文脈と読者を考慮してください。
Unraid OS は世界中のユーザーを対象としているため、専門用語、俗語、慣用句は避けます。これらは英語を母語としない読者を混乱させ、翻訳作業を複雑にするおそれがあります。
対象読者: すべてのレベル向けに書く
読者は、システム内部を理解している Linux の専門家から、初めて Unraid を操作する初心者までさまざまです。
専門家と初心者のどちらも無理なく理解できるよう、明確で包括的な表現を心がけてください。
ABC メソッド: 正確さ、簡潔さ、明瞭さ
特に重視するのは次の点です:
- 正確さ: 内容が正確で、十分にテストされていることを確認します。
- 簡潔さ: 必要な詳細を損なわずに、簡潔にまとめます。
- 明瞭さ: 平易な言葉を使い、内容を理解しやすい構成にします。
構文
Unraid Docs では、Markdown 書式と特定のテキストスタイルを組み合わせて、ユーザーが UI 要素をすばやく識別し、WebGUI を操作できるようにしています。
| 要素の種類 | スタイル規則 | Markdown 構文 | 例 / 説明 |
|---|---|---|---|
| オプションまたはボタン名 | 太字 | **text** | Done を選択 |
| ユーザー入力値 | 斜体 | *text* | 50gb を入力 |
| ナビゲーションパス | 太字 + 斜体; → を使用 | ***nav1 → nav2*** | 設定 → ディスク設定 |
| タブラベル | 太字 | tab_name | 選択するタブの名前 |
| チェックボックスラベル | 太字 | checkbox_label | チェックボックスオプションのラベル |
| ドロップダウンメニューのオプション | 斜体 | dropdown_option | ドロップダウン内で選択可能なオプション |
| ダイアログタイトル | 見出し 3 | ### Dialog Title | ポップアップダイアログまたはモーダルウィンドウのタイトル |
| ツールチップテキスト | インラインの斜体 | tooltip text | ホバー時に表示される短い説明 |
| メニュー項目 | 太字 + 斜体 | Menu → Submenu → Item | 入れ子のメニュー内を移動するための表記 |
| CLI とシステム出力 | 等幅フォント（インラインコード） | `text` | http://tower.local に移動 |
| エラーメッセージ | 等幅フォント（インラインコード） | `Error: message` | 正確なエラー文字列またはログ |
| ドキュメントタイトル | 見出し 1 | # Heading | （表示結果）<h1>Heading</h1> |
| ドキュメントのセクション | 見出し 2 | ## Heading | （表示結果）<h2>Heading</h2> |
| ドキュメントのサブセクション | 見出し 3 | ### Heading | （表示結果）<h3>Heading</h3> |
見出しレベル 2（##）以下は、ページの目次（TOC）のサイドバーに表示され、簡単に移動できます。
リストと表の書式設定
リストや表のような構造化要素を効果的に使うことで、情報の明瞭さが向上し、理解を助け、素早い参照に役立ちます。
リスト
リストは、重要なポイントや手順を把握、記憶、追従しやすくします。主な種類は 2 つあり、それぞれ明確な用途があります:
-
順序なしリスト（箇条書き）: 順序を示さずに関連項目をまとめるときに使用します。 例: 「一般的な Unraid OS ツールの一覧。」
-
順序付きリスト（番号付き）: 必要な順序や手順を示すときに使用します。 例: 「array を開始するには...」
- コロンで終わる明確な導入文でリストを始めるようにしてください。
- 一覧しやすく覚えやすいように、順序なしリストは最大 4〜6 項目に抑えます。長いリストは表のほうが適している場合があります。
表
表は、情報を行と列にまとめて関連データを整理するのに適しており、比較をより迅速かつ正確にします。
- 複数の関連データポイントを並べて比較する必要がある場合は、表を使用します。
- 1〜2 セルしかない表は避け、代わりに箇条書きリストまたは文を使用してください。
- 表の目的と内容を説明する文を添えて導入します。
略語、頭字語、イニシャリズム
読者の混乱を減らすため、略語については次の原則に従ってください:
- 略語 は単語を短くした形ですが、Unraid Docs では広く認知されている場合を除き、通常は不要です。
- 頭字語 は、他の単語の頭文字から新しい語を作ります（例: RAID）。
- イニシャリズム は、1 文字ずつ発音する頭文字を使います（例: OS、ZFS）。
推奨:
- 読者にとってなじみのある、既存のよく知られた頭字語やイニシャリズムを優先してください。
- 簡潔さのためだけに、新しい略語を作らないでください。
- あまり一般的でない頭字語やイニシャリズムは、初出時に必ず展開形を記し、その後にかっこ内で略語を付けてください。 例: Virtual Machine Disk (VMDK)
他のドキュメントやサイトへのハイパーリンク
戦略的なリンクにより、読者は関連トピックを調べやすくなり、理解も深まります。実用的でアクセスしやすいハイパーリンクのために、次のガイドラインに従ってください。
リンクテキストのガイドライン
- リンクテキストはリンク先を明確に示し、すべての読者がリンクの目的を把握できるようにする必要があります。
- 「Click here」や「Read more」のような曖昧なリンクテキストは、文脈が不足するため避けてください。
- 生の URL をインラインのリンクテキストとして使わないでください。
リンクの書式
- インラインの Markdown リンクを使用します:
You can also check our [getting started guide](../unraid-os/getting-started/quick-start-guide.mdx).
- 常に、利用可能な中で最も関連性が高く、権威ある資料にリンクしてください。
用語集の用語を追加する
Unraid Docs では、技術用語の一貫性とアクセシビリティを確保するため、中央集約型の用語集システムを使用しています。用語集エントリは、ルートディレクトリにある glossary.yaml ファイルで管理されます。
用語を追加または更新するには:
- 次のテンプレートを使って
glossary.yamlを編集します:
GlossaryTerm:
term: Display Name
def: Full definition text.
link: <a href="https://example.com">Optional detailed link</a>
-
ツールチップ機能を追加するには、次の構文を使用して文書内でその用語を参照します:
%%Term|GlossaryTerm%%...ここで、パイプの左側は表示したいテキスト、右側は YAML ファイル内の対応する用語エントリです。
-
- 用語集ページ は、新しい用語を含むよう自動的に更新されます。