botr-faq.md

Book of the Runtime (BotR) FAQ

(これは https://github.com/dotnet/coreclr/blob/8d3936bff7ae46a5a964b15b5f0bc3eb8d4e32db/Documentation/botr/botr-faq.md の日本語訳です。対象rev.は 8d3936b ）

BotRとは?

この Book of the Runtime は、CLRとBCLのコンポーネントを説明するドキュメントの集合体です。これらは、アーキテクチャや、変更のない部分に主眼を置いたものであり、コードベースの注釈を意図したものではありません。

これは、このドキュメント自体も含め、元々はMicrosoft社内で2007年頃までに作成されたものでした。開発者らは、各自の担当部分についてまとめる責任を負っていました。これが、チームに新規参入した開発メンバーを助け、チームを超えた製品アーキテクチャの共有が促進されたのです。

私たちは、CoreCLRがGitHubでオープンソースで公開された現在、このBotRがさらに価値のある存在となったことに気付きました。私たちは、BotRの各チャプターを公開することで、新しいCLR開発者の集団を助けます。

BotRの各ドキュメントは、一定の視点に基づいて、所定の時期に所定の作成者によって書かれています。私たちは、これらのドキュメントを「2015年版」として書き換えることは、あまり良くないだろうと考えました。これらのドキュメントは、いくつかの些細なスペルミスの修正やマークダウンへの変換以外では、ありのままで残されています。とはいえ、これらのドキュメントを改善するためのPRは受け付けます。

BotRの主な対象者は誰?

• バグフィックスに従事していて、その対象エリアに関する、コンポーネントのハイレベルの概要を必要とする開発者
• 何らかのコンポーネントに依存する新機能を開発していて、その新機能が従来のコンポーネントと正しく協調動作するか十分に確認したい開発者
• 所定のコンポーネントをメンテナンスする新しい開発者も、このチャプターが必要となります。

この BtoR のチャプターにあるべきものは?

このBook of the Runtimeのチャプターの目的は、機能仕様書およびソースコードからでは容易に再構築できないような情報を把握し、チームメンバー間でハイレベルの意思疎通を可能にすることです。コンセプトを説明し、トップダウンの記述を提示し、そして一番重要なこととして、なぜ私たちがこれらの設計上の決定を下したのかを説明します。

これはデザインドキュメントとはどう違うの?

デザインドキュメントは、実装を始める前に書くものです。BotRのチャプターは、通常、その機能が実装された後に、デザイン上の選択肢の優劣を判断して、その中からひとつを選んだ状態で（また、もしかしたら将来改善された設計を用いる計画がある状態で）、全ての詳細部分についてより良いアイディアがある状態で（実際に実装およびテストを経ないと、考えるのが非常に困難なものもあるでしょう）、書かれるものです。そのため、存在理由やデザイン背景事情などについては、ずっと良い状態で記述することができます。

初めて開発に参加するのでどの機能にも詳しくないけど、どうすれば協力できる?

BotRの最重要目的のひとつは、新しい開発者が早く参入できるようになることであり、新しい開発者もBotRの多大な協力者となりえます。どのように協力できるかというと:

• レビュアーになる! もし説明が明確でなかったり、より上手く説明できるのであれば、そのチャプターの作成者と連絡をとって、その人と話を通して、より理解しやすい内容にすることができます。
• 読んでいるエリアに慣れ親しんできたら、BotRチャプターをざっと眺めて、間違いを発見したりアップデートが必要な部分を見つけて、自ら修正することができます。
• 新しいチャプターやその一部分を書く作業に名乗りを上げる。これは緊張する仕事かもしれませんが、知識を収集するだけのところから始めて、そのエリアについて自習し、だんだんと新しいBotRチャプターとしてまとめていくと良いでしょう。

BotRレビュアーの責務とは?

あなたがレビュアーであれば、レビューするチャプターについて、建設的なコメントを出すことが期待されています。技術的な詳細、ライティング スタイル、内容の範囲など、あらゆる側面についてコメントできます。留意事項としては、BotRはほぼデザインとアーキテクチャを扱うものであり、それらは必ずしも明瞭ではないということです。実装の詳細について踏み込むためのものではありません。それを念頭に置いてください。

私は 本当に BotRチャプターの作業をする時間が無くて、いつも他にやるべきことがあるようなんだ。どうすればいい?

BotRの作業をするにあたって検討に価するやり方をいくつか示しましょう。

• 作業を分散する。ワークアイテムを「私は月曜から木曜まで私のチャプターの作業をしなければならない」とするのではなく、コーディングやバグフィックスの合間に、息抜きとしてやるとか、気分転換のひとつとして進めるのです。私はそうやって細かい時間をチャプターの作業に費やす方が、連続した日数を確保して進めるという現実にはいつも困難であるやり方よりも、ずっと簡単であると思いました。
• 誰か他の人にそのチャプター全体あるいは大部分を書いてもらう。いや冗談ではありません。これは新しい開発者を取り込むのに非常に有効な方法です。もしあなたが新しい開発者を自分のエリアでメンターするのであれば、その機能のエリアについて彼らに説明する時間をとり、もしまだ無ければ彼らにBotRチャプターを書かせるようにするのです。もちろんそのレビューはしましょう。
• 他に存在しているドキュメントを使いまわす。.NETの機能に関する、MSDNドキュメントやブログ投稿があるでしょう。それらは間違いなくBotRチャプターの基盤として使えます。