ボイスとトーンのガイドライン

.NET のドキュメントは、IT プロフェッショナルや開発者を含むさまざまな人が .NET を学習するため、および通常の作業で使用するために閲覧します。 作成者の目標は、閲覧者が目的を果たす過程で助けとなる優れたドキュメントを作成することです。 ここで示すガイドラインは、それをサポートするものです。 このスタイル ガイドには、次の推奨事項が含まれています。

会話的なトーンを使用する

次の段落は、会話的なスタイルで記述されています。 その後に続く段落は、より学術的なスタイルです。

適切なスタイル

ドキュメントには会話的なトーンを使用します。 あなたは Microsoft のチュートリアルまたは説明を閲覧するとき、まるで作成者と会話しているように感じるはずです。 エクスペリエンスは、あなたにとって堅苦しくなく、会話的で、かつ有益なものであるはずです。 閲覧者は、まるで作成者が自分に向けて概念を説明しているのを聞いているように感じするはずです。

不適切なスタイル

会話的なスタイルと、技術的なトピックにおけるより学術的な表現にみられるスタイルとは対照的であることに誰でも気づくことができます。 そのような資料は非常に有用ですが、作成者は Microsoft のドキュメントとは異なるスタイルでそれらの記事を書いています。 学術的な雑誌を閲覧するとき、誰でも書き方のトーンおよびスタイルがかなり異なることに気づきます。 誰でも非常に無味乾燥なトピックの退屈な説明を読んでいると感じます。

二人称で書く

次の段落では二人称が使われています。 この後に続く段落では三人称が使われています。 二人称で書いてください。

適切なスタイル

閲覧者に直接話しているかのように記事を執筆してください。 多くの場合、二人称を使います (この 2 つの文のように)。 二人称は、単語 'you (あなた/ご自分/お客様)' を使用することを常に意味するとは限りません。 直接閲覧者に向けて書きます。 命令文で書きます。 ご自分の記事の閲覧者に何を学んでもらいたいかを伝えます。

不適切なスタイル

作成者は三人称で書くことも可能です。 その人称では、作成者は閲覧者を言及するときに使用する何らかの代名詞または名詞を探す必要があります。 閲覧者はこの三人称のスタイルが読んでいて魅力や面白みに欠けることにしばしば気づくことがあります。

能動態を使用する

記事は能動態で書きます。 能動態とは、文の主語がその文の行為 (動詞) を行うことを意味します。 能動態は受動態と対照を成しており、受動態は文の主語が行為を受けるように配置されます。 次の 2 つの例を対照させてください。

コンパイラはソース コードを実行可能なコードに変換しました。

ソース コードはコンパイラによって実行可能なコードに変換されました。

最初の文では能動態が使用されています。 2 番目の文は受動態で書かれています。 (この 2 つの文も各スタイルの例を別に示します)。

より読みやすいという理由から、能動態を推奨します。 受動態にすると、読みにくくなる場合があります。

語彙が限られている閲覧者のために執筆する

あなたはご自分の記事を使用して世界中の対象読者に情報を伝えます。 閲覧者の多くは英語のネイティブ スピーカーではなく、あなたと同じ英語の語彙を持っていない可能性があります。

しかし、それでもあなたは技術の専門家を対象にして記事を書いています。 閲覧者にはプログラムに関する知識があり、プログラミング用語について特定のボキャブラリを持っていると仮定することができます。 オブジェクト指向プログラミング、クラスとオブジェクト、関数とメソッドなどはよく使われる用語です。 ただし、あなたの記事を閲覧するすべての人が、コンピューター サイエンスの正式な学位を取得しているわけではありません。 "べき等" などの用語を使用する場合は、おそらく定義する必要があります。例:

Close() メソッドはべき等です。すなわち、このメソッドは複数回呼び出すことができ、その結果はこのメソッドを 1 回呼び出した場合と同じです。

未来時制を避ける

英語以外の言語の中には、未来の概念が英語と同じではないものがあります。 未来時制を使用することで、ドキュメントが読みにくくなる可能性があります。 さらに、未来時制を使用する場合、いつのことなのかという素朴な疑問が生まれます。 つまり、"Learning PowerShell will be good for you (PowerShell を学ぶことはあなたのためになることでしょう) " と表現した場合、閲覧者には、ためになるのはいつのことなのか、という素朴な疑問が生じます。 このため、単に "Learning PowerShell is good for you (PowerShell を学ぶことはあなたのためになります)" と表現します。

それは何 - だから何なの?

新しい概念を閲覧者に紹介するときは必ず、その概念を定義して初めて、それが有用である理由を説明します。 閲覧者は利点 (あるいは他のこと) を理解するには、事前にどんなものなのかを理解しておくことが重要です。