コンテンツガイドライン

このドキュメントは公式ドキュメントにどのようなものが含まれるべきかを説明するものです。以下に、利用しやすい内容を書くためのいくつかの原則と推奨を示します。

達成したい目標は2つあります:

** ユーザーに共感する。 ** ユーザーがドキュメントから学ぶ時に理解しやすいように書くべきです。
** 完全なリファレンスマニュアルを書く ** 。この目標はプログラミングの基礎を教えることではありません。その代わりに、Godotの機能がどう作用するかのリファレンスを提供することが目標です。

ガイドラインと原則

以下は私たちが守るべきガイドラインです。とはいえ、これらは厳密なルールではなく、トピックによっては1つ以上を破らなければならないこともあります。それでも、私たちは上記の2つの目標を達成するために努力しなければなりません。

完全かつ利用しやすいドキュメントの記述

** ドキュメントが書かれない限り機能は存在しません ** 。ユーザーがある機能や動作についての情報を見つけられないなら、それらは存在しません。私たちはGodotが行うすべての事を網羅することを保証しなければなりません。

注釈

エンジンの機能を追加したり更新したりするときは、ドキュメントチームがそれを知る必要があります。コントリビューターは、自分の作業がマージされ、ドキュメントが必要になったら godot-docs リポジトリに issue をオープンしてください。

文書の長さは **1000 ワード以内に収めるよう最善を尽くしてください ** 。ページがその閾値を超える場合は、2つに分けることを検討してください。ページ数を制限することで簡潔な文章を書かざるを得なくなりますし、大きな文書を分割して各ページがそれぞれの問題に集中できるようになります。

各ページやセクションには、そのページがどのような問題に取り組んでいるのか、ユーザーに何を教えるのかを明確に示す必要があります。ユーザーは、自分が読んでいるものが今遭遇している問題を解決するための正しいガイドかどうかを知る必要があります。例えば、 "シグナル " という見出しの代わりに、 "シグナルによる変化への反応 " と書くことを検討してください。2つ目のタイトルは、シグナルの目的が何であるかを明確にしています。

注釈

セクションのタイトルが長いと、サイドメニューの項目が長くなりナビゲーションが煩雑になります。見出しの長さは英語5ワード以内にするようにしましょう。

もしそのページが他のGodotの機能に関する特定の知識を前提としている場合は、そのことに触れ、対応するドキュメントにリンクしてください。例えば、物理のページではシグナルを使うかもしれません。その場合、シグナルのチュートリアルが前提条件であることを示すのがよいでしょう。また、ドキュメントの範囲外の前提条件について、他のウェブサイトにリンクすることもできます。例えば、入門のセクションからプログラミング入門サイトへリンクしたり、数学のセクションから数学理論を教えるウェブサイトにリンクしてもいいでしょう。

認知的負荷の制限

ドキュメントを読むのに必要な認知的負荷を抑えましょう。よりシンプルで明示的な言葉を使えば、人々の学習効率もより高まります。そのためには以下の方法があります:

可能な限り、一度に新しいコンセプトを1つだけ導入する。
ドキュメント作成ガイドラインで推奨される通り、シンプルな英語を使う。
1つ以上の 具体的な使用例 を含める。 foo 、 bar 、 baz などの名前を使った例よりも、実際の例を優先してください。

より複雑な言葉や抽象的な例を理解できる人も多いかもしれませんが、残りの人を取り残すことになります。理解しやすい文章と実践的な例は、誰にとっても有益です。

常に ユーザーの立場に立つ 努力をすること。私たちは何かを完全に理解すると、それを当然のものと思ってしまいます。新規ユーザーのために詳細を考えることを怠ることもあるかもしれませんが、 良いドキュメントとは、ユーザーが読んでいる時の立場に合うものです 。私たちは、各機能の能力や使用目的について、できるだけわかりやすい言葉で説明しなければなりません。

その機能やコンセプトについて学ぶとき、最初に何を知る必要があったかを思い出してみてください。どんな新しい用語を覚える必要がありましたか？何に戸惑いましたか？何を理解するのが一番難しかったですか？自分の仕事をユーザーにレビューしてもらいたいでしょうから、まずその機能について書く前に説明の練習をすることをお勧めします。

注釈

プログラミングの基礎は、Godotのような複雑なエンジンを使うための前提条件です。変数や関数、クラスについて話すのは構いません。しかし、 " メタプログラミング " のような特殊な用語よりも、平易な言葉を優先するべきです。もし正確な用語を使う必要があるなら、必ず用語の定義をしてください。