コンテンツガイドライン¶
私たちはあなた自身の執筆スタイルを採用することを奨励しますが、いくつかのルールはまだ明快さを維持し、読者がコンテンツを簡単に理解できるようにするために適用されます。
重要
貢献する前に、 RSTガイドラインとチートシート と :doc:のメインページを読むことを強くお勧めします。
ドキュメントの組織¶
特定のトピックに関するドキュメントを作成する場合は、ページを同じフォルダ内に保持します。
ほとんどのトピックでは、単一のページがジョブを実行する必要があります。ドキュメントの適切なセクションに配置します (例: CRMアプリに関連するコンテンツは、 :menuselection:`User Docs --> Sales --> CRM`の下にあり、 :ref:`document structure <contributing/content/structure>`ガイドラインに従います。
複雑なトピックを扱う場合、そのすべての側面を網羅するには複数のページが必要になることがあります。 通常は、すでに一部が記述されているトピックにドキュメントを追加することになるでしょう。その場合は、新しいページを作成して他の関連ページと同じ階層に配置するか、既存のページに新しいセクションを追加してください。トピック全体を一から文書化する場合は、内容を複数の子ページに分割し、それらをディレクトリ内の親ページ（ TOC ページ）から参照するように構成します。可能な限り、子ページだけでなく親ページにも内容を書くようにしてください。親ページをナビゲーションメニューからアクセス可能にするには、 show-content メタデータディレクティブを使用します。
注釈
可能な限りコンテンツの複製は避けてください。トピックが既に別のページで文書化されている場合は、既存の情報を繰り返すのではなく、 reference を使用します。
重要
.rst ファイルを削除または移動する場合は、ブランチのバージョンに対応する redirects フォルダ内のテキストファイル（例： 17.0.txt ）を更新してください。その際、該当セクション（例： # applications/sales ）の末尾に新しい行を追加します。その行には、まず旧ファイルのパス（リダイレクト元）を記述し、スペースを空けてから新しいファイルのパス（リダイレクト先）を記述します。たとえば、 unsplash.rst を applications/websites/website/configuration から applications/general/integrations に移動する場合は、 # applications/websites セクションの下に以下のようなエントリを追加します：
applications/websites/website/configuration/unsplash.rst applications/general/integrations/unsplash.rst
ドキュメントの構造¶
セクションとサブセクションごとにテキストを整理するために、異なる**見出しレベル**を使用します。 見出しは、ドキュメント内だけでなく、ナビゲーションメニュー(H1のみ)やサイドバー(H2からH6)にも表示されます。
H1: ページタイトル
ページタイトル は、コンテンツが何であるかを素早く明確に理解することができます。
このセクションの*content*は**ビジネスの視点**からの今後のコンテンツについて説明します。 これはマーケティングではなくドキュメントなので、Odooを重視すべきではありません。 ページタイトル (H1) の下で、リード段落 を始めます。これは、読者が正しいページを見つけたことを確認するのに役立ちます。 次に、**このトピックのビジネス的側面**について説明します。 |
||
H2: セクションタイトル (設定)
この最初のH2セクションでは、機能の設定、または特定の目標を達成するための前提条件について説明します。
|
||
H2: セクションタイトル（メインセクション）
区別するアクションまたは機能がある数だけメインセクションを作成します。
|
||
H3: サブセクション
サブセクションは非常に具体的な点を評価するのに最適です。
|
||
H2: 次のセクション |
||
タイトルや見出しを書くには:
簡潔にしましょう: **文章、質問、タイトルは「How to」から始まります。
**代名詞**は使用しないでください。特に2人目（あなた/あなたの）です。
**文の場合**を使用してください。これは大文字にするだけです。
タイトルまたは見出しの最初の単語
植民地の後の最初の単語;
固有名詞(ブランド名、製品名、サービス名など)。
注釈
ほとんどのタイトルおよび見出しは概念を参照し、フィーチャーまたはモデルの名前を*表しません*。
彼らが適切な名詞を伴わない場合は、頭字語の単語を大文字にしないでください。
見出しの動詞はアクションを表すことが多いので問題ありません。
書くスタイル¶
ドキュメントを書くことは、ブログや他の媒体で書くこととは違います。 読者は、必要な情報を見つけるためにコンテンツをスキムする可能性が高いです。 ドキュメントは**情報を伝えて説明する**場所であり、説得して促進するのではないことに注意してください。
ちなみに
適切な場合は命令的な気分を選ぶことによって、可能な限り*あなた*を使用しないでください。 しかし、読者に直接対処することを避けるために文章を複雑にしないでください。
Example
Spelling¶
ドキュメント全体でアメリカ英語のスペルと文法を使用してください。
整合性¶
一貫性はすべてのものへの鍵です。
書き方が**一貫性**があることを確認してください。 既存のコンテンツを変更する場合は、既存のトーンとプレゼンテーションを一致させるか、独自のスタイルに合わせて書き換えてください。
大文字化¶
文法形態format@@0¶
英語では、説明と説明は通常**現在時制**の使用が必要です。 一方、*未来時制*は、特定の事象が真皮的に起こる場合にのみ適切です。
Example
リスト¶
リストのヘルプは、明確かつ簡潔な方法で情報を整理し、読みやすさを向上させます。 彼らは重要な詳細を強調するために使用されます, 体系的な方法でステップを通じて読者を導きます, 等.
シーケンスが重要な場合、例えば、命令、プロシージャ、または特定の順序で実行する必要があるステップを使用します。
項目の順序が問題でない場合、箇条書きリストを使用します。例えば、機能、フィールド、オプションなどのリスト。
ちなみに
説明にインラインテキストを使用するか、リスト項目が3つ以下の場合に使用します。
適切な場合は、 :ref:`ネストされたリスト <contributing/rst/nested-list>`を使用して箇条書きと番号付きリストを結合します。
同じリスト項目内の簡単なステップをグループ化することを検討してください。例えば: に移動し、 New をクリックします。
完全な文章を形成する場合にのみ、リスト項目の末尾にピリオドを使用します。
Example
箇条書きリスト
:guilabel:`補充`レポートには以下のフィールドがあります。
Product: 補充が必要な製品
Location: 製品が格納されている特定の場所
Warehouse: 製品が格納されている倉庫
オンハンド: 現在利用可能な製品の量
番号付きリスト
新しいウェブサイトページを作成するには、次のように進みます:
関連項目
アイコン¶
:ref:`icons <contributing/rst/icons>を使用して、ユーザーインターフェイスの要素を特定し、長い説明の必要性を減らしましょう。 括弧内の記述子ですべてのアイコンを同期させます。
Example
開発者モードが有効になると、 (bug ) アイコンをクリックすることで開発者ツールにアクセスできます。
画像¶
テキストを示すためにいくつかの画像を追加することは、読者がコンテンツを理解し、記憶するのに役立ちます。 しかし、画像はテキストを置き換えるべきではありません:書かれた命令は、視覚的な補助に頼らずに、自分自身で完全かつ明確である必要があります。 たとえば、画像を控えめに使用して、特定のポイントを強調したり、例を明確にしたりします。
重要
PNGファイルを pngquant <https://pngquant.org>`_ で圧縮することを忘れないでください。
スクリーンショット¶
スクリーンショットはコンテンツブロックの幅に合わせて自動的にサイズが変更されます。これは、幅が広すぎると低解像度の画面では読み取れないことを意味します。 絶対に必要でない限り、アプリの全画面スクリーンショットを避け、768〜933ピクセルの範囲で画像が広くないことを確認することをお勧めします。
スクリーンショットを改善するためのヒントをいくつかご紹介します。
**ウィンドウのサイズを変更する*または*ブラウザの開発ツール*を開き、幅を変更することによって、ブラウザの幅を**リサイズ**します。
ウィンドウ全体を維持するのではなく、関連領域を**選択** します。
不要な情報を削除し、該当する場合は サイズ変更 列を削除します。
重要
長方形や矢印などのマークアップをスクリーンショットに使用しないでください。 代わりに、画像をクロップして最も関連性の高い情報を強調し、テキストの指示が画像に頼らずに明確かつ自明であることを確認します。
Example
良い例 (ブラウザのリサイズ、不要な列なし、列の調整幅、トリミング):
不正な例 (全画面表示):
メディアファイル¶
メディアファイル名:
は**小文字**で書かれています;
はメディアのコンテンツに 関連性 です。(例:
screenshot-tips.gif);単語を ハイフン
-で区切ります(例:awesome-filename.png)。
各RSTファイルには、メディアファイルを保存するための独自のフォルダがあります。フォルダの名前はRSTファイルの名前と同じである必要があります。
例えば、ドキュメント doc_filename.rst`は、``doc_filename` フォルダに配置されている2つの画像を指します。
├── section
│ └── doc_filename
│ │ └── screenshot-tips.gif
│ │ └── awesome-filename.png
│ └── doc_filename.rst
ALTタグ¶
ALTタグ は画像への*テキスト代替*です。このテキストはブラウザが画像のレンダリングに失敗した場合に表示されます。 視覚障害のあるユーザーにも役立ちます。 最後に、Googleなどの検索エンジンで画像が何であるかを理解し、正しくインデックスを作成するのに役立ちます。 これにより、 SEO が向上します。
良いALTタグは次のとおりです。
関連項目