最終更新日 2022年02月15日(火)

この記事には、Heroku Dev Center の表現と文体のガイドラインが含まれています。Heroku Dev Center の記事を記述または更新する場合は、一貫性のあるコンテンツをユーザーに提供するために、このガイドに従ってください。

直接的に

Dev Center では、事実に基づいた直接的な文体を使用します。はっきりと、確実に主題を伝えるようにしてください。

“should” (～のはずだ)、"seems" (～のようだ)、"probably" (おそらく) のようなあいまいな表現は、別の表現に置き換えてください。次は悪い例です。

It seems like every SSL reseller packs their certificates in a slightly different way with slightly different filenames. (すべての SSL 再販業者が、若干異なる方法で、わずかに異なるファイル名を使用して証明書をパックしているようです。)

次は良い例です。

SSL resellers use a variety of naming conventions when packaging certificates. (SSL 再販業者は、証明書をパッケージ化するときにさまざまな命名規則を使用します。)

ユーザーの目標に焦点を絞る

実際のユースケースに即したコンテンツを作成するようにしてください。

事実に基づいているというのは、事実のみを伝えるという意味です。必要な概念情報は、それに関連するタスクをユーザーが実行する場合にのみ提示します。無関係な概念は別の記事で扱います。記事の相互リンクはいつでも可能です。

簡潔に

使用する文字 (単語) 数をできるだけ少なくしてください。テキストは簡潔に記述します。長く複雑な文は避けてください。

短縮形

できる限り短縮形を使用します (英語の場合)。

肯定的に

可能な限り、否定的ではなく肯定的な文を記述します。

次は悪い例です。

Don’t use a database with a plan smaller than standard-4​ with Heroku Connect in production environments. (本番稼働環境の Heroku Connect では、standard-4​ 未満のプランのデータベースを使用しないでください。)

肯定的に書き換えます。

Use a database with a standard-4​ or larger plan with Heroku Connect in production environments. (本番稼働環境の Heroku Connect では、standard-4​ 以上のプランのデータベースを使用してください。)

二人称の語り口を使用する

二人称の視点​では “you” を使用して読者に語りかけます。これは技術文書では適切です。対象を読者に絞り、指示形や命令形を使って記述できるからです。

Dev Center の記事では、一人称視点)​ (“I” や “we”) ではなく二人称 (“you”) を使用してください。

次のように、執筆者の個人的な経験を読者に関連付ける記述は避けてください。

Based on our own experience managing remote assets, we created the foo​ gem so you can transparently upload your static assets to S3 on deploy. (リモートアセットの管理に関する我々自身の経験に基づき、我々は、読者がデプロイ時に静的アセットを S3 に透過的にアップロードできるように foo gem を作成しました。)

代わりに、読者自身のメリットに基づいて概念を提示してください。

The foo​ gem enables you to upload static assets transparently at deploy time. (foo gem を使用すると、デプロイ時に静的アセットを透過的にアップロードできます。)

能動態を使用する

可能な限り能動態を使用してください。受動態を能動態に書き換えるときに、文の意味が変わらないようにしてください。

以下のように、受動態のほうが適切な場合もあります。

• 能動態を使用するとぎこちない構文になる場合
• 主語が不明であるか、文の中心ではない場合
• ユーザーを責めるような表現を避けたい場合

実際の主語を特定して、受動態を能動態に書き換えます。次は悪い例です。

The data is entered. (日付が入力されます。)

次は良い例です。

The user enters the data. (ユーザーが日付を入力します。)

受動態を命令法に書き換えることもできます。次は悪い例です。

このコマンドでは、名前の引数が指定される必要があります。

次は良い例です。

このコマンドでは、名前の引数を指定します。

現在形を使用する

可能な限り現在形を使用してください。次に示すのは、過去形を使用する悪い例です。

This guide was created to describe the voice and tone of a well-written Dev Center article. (このガイドは、適切に記述された Dev Center の記事の態と文体について説明するために作成されました。)

次は良い例です。

This guide describes the voice and tone of a well-written Dev Center article. (このガイドでは、適切に記述された Dev Center の記事の表現と文体について説明します。)

同様に、未来形ではなく現在形を使用してください。次は悪い例です。

After you log in, the registration dialog will appear. (ログイン後、登録ダイアログが表示されるでしょう。)

次は良い例です。

After you log in, the registration dialog appears. (ログイン後、登録ダイアログが表示されます。)

その他のガイドライン

この記事には、Heroku Dev Center の表現と文体のガイドラインが含まれています。記事を記述するときは、スタイル​およびコンテンツのガイドライン​にも従う必要があります。詳細は、「Dev Center の記事の記述​」を参照してください。