Heroku Dev Center のコンテンツのガイドライン

最終更新日 2023年05月04日(木)

Heroku のチームメンバーおよびアドオンプロバイダーは、Dev Center の記事を記述し、維持管理しています。Dev Center 以外のコントリビューターも、独自のドキュメントプロジェクトの規約を確立するための参考として、この記事を使用できます。

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

記事の長さ

記事の長さの上限は 1,500 語が目安です。ただし、Platform API リファレンス​のような純粋なリファレンス記事は例外です。

記事が冗漫でないか読み直してみてください。Hemingway​ のようなアプリなら、複雑すぎる文を指摘してくれます。

1,500 語を超えるような記事は、目的が 1 つに絞り切れていないことがあります。記事が何を解決するのかを注意深く定義し、目的ごとに記事を小さく分割してください。

記事タイトルと導入部

検索のためにタイトルを最適化します。トピックとの関連性が最も高いキーワードを含めます。必ず、タイトル形式で単語の先頭を大文字化​してください。

概念またはリファレンストピックの場合、製品名または機能名のみをタイトルにすることができます。タスク指向のトピックを含む記事は、動名詞​で始まるタイトルにします (英語の場合)。次に例を示します。

Java を使用して Heroku でリレーショナルデータベースに接続する

記事内容の短い概要を記事の先頭に記述します。どのようなユースケースや問題を記事が解決するのかを具体的に述べます。

複雑さ

特定のテクノロジに関する概念記事では、ユースケース付きで説明します。高度な、あるいは希少なユースケースを紹介する前に、最も普遍的に応用できるテクノロジの概念について説明してください。

読みやすいように、また流し読みがしやすいように、トップレベルのセクション (H2) が長い場合は (H3、H4 などの) サブヘッダーを使用して分割してください。

日付

日付は必要な場合にのみ使用してください。"現在"、"先週"、"昨年"、"新しい" などの使用には注意してください。これらの表現は、ユーザーがある特定の時点でドキュメントを読んでいることが前提になります。

ほとんどの場合、日付の使用は避けることができます。サポート終了予定などに関して日付を使用する必要がある場合は、次のガイドラインに従ってください。

  1. 特定の Heroku Changelog アイテムを参照します。
  2. 執筆者側または Heroku Dev Center チーム側で、将来、記事から日付を削除するためのリマインダーを設定します。

コードリポジトリの例

サンプルアプリケーションが最新の状態を維持していることは、執筆者の責任において保証します。記事を執筆する Heroku スタッフメンバーの場合は、GitHub リポジトリのすべての例が heroku​ 組織に存在する必要があります。

可能であれば、デプロイ可能なサンプルアプリケーションを含ます。デプロイ可能なリファレンスアプリケーションは、特定のアプローチの全体像を示すための優れた手段です。このリファレンスにより、記事では、より広範なソリューションの実装に関連した中心的な手順に焦点を当てられるようなります。

コンパニオンアプリケーションが記事に含まれる場合は、記事の導入部の後に次の注意書きを添えてください。

​>note
>この記事の[リファレンスアプリケーション](https://github.com/xyz)​のソースは
>GitHub で入手できます。

ローカルと Heroku の両方で標準の CLI コマンドを使用してアプリケーションを実行する手順の README を GitHub プロジェクトに含めてください。

包摂性

性別固有の代名詞および所有格は避けてください。二人称単数形 (you) を使用する、代名詞を省略する、名詞を複数形にするなどの方法を試してみてください。三人称代名詞の使用が避けられない場合は、"they" を使用してください。"he" または “she” および “his” または “her” は避けてください。

“they” を三人称単数形として使用する場合は、あいまいな代名詞の参照を避けるように注意してください。たとえば、単数形と複数形の名詞が 1 つの文に含まれている場合に、単数形を参照するために “they” を使用しないでください。

架空のユーザーを列挙するスクリーンショットまたはサンプルデータを作成するときは常に、多様なアイデンティティを含めるようにしてください。

グローバルな読者層に配慮し、口語表現や特定の文化に関する言及をコンテンツに含めるときは慎重に検討してください。

記事ではインクルーシブな表現を使用してください。

次の表ページの内容には、感情および理性の面で挑発的と取られる可能性がある、インクルーシブでない表現を敢えて含めています。

不許可 許可
ブラックリスト ブロックリスト
ブラックアウト ブロックアウト
ブラウンアウト 低い可用性
マスター メイン、リーダー、プライマリ
スレーブ フォロワー、セカンダリ、スタンバイ、レプリカ
ホワイトリスト 許可リスト

インクルーシブでない用語がサードパーティのシステムで使用されているため、やむを得ずその用語を使用する場合は、記事の冒頭に次のコールアウトを含めてください。

Salesforce では、平等に関する会社としての価値観に適合するよう、インクルーシブでない用語を可能な範囲で変更しています。当社製以外のシステムに関する記述では、インクルーシブでない用語をそのまま使用していますが、Heroku では開発者コミュニティに対し、よりインクルーシブな表現の採用を奨励しています。Heroku では、インクルーシブでない用語について、技術的な正確さのために必要でなくなった時点での更新を予定しています。

セクション見出し

タイトル形式で単語の先頭を大文字化​します (英語の場合)。タスクに関するセクションでは、動詞の命令形で始まる見出しにします。次に例を示します。

マッピングを作成する

スペリング

辞書

スペリングについて疑問に感じた場合は、Random House Unabridged Dictionary をベースにした dictionary.com​ を参照してください。

Salesforce のスタイルガイドには、数字のスペリングのガイドライン​と複合語のスペリングのガイドライン​が含まれています。

商標、ブランド名、機能名

詳細は、「Heroku Dev Center のスタイルのガイドライン​」を参照してください。

単語リスト

以下の単語には、複数のスペリングまたは用法のあいまいさがあります。Dev Center でのスペルの規定と併せて示します。

  • add-ons​: ​addons​ ではありません。インスタンスまたはサービスを参照するときは小文字を使用します (例: installing an add-on)。Heroku 製品を参照するときは単語の先頭を大文字にします (例: Heroku Add-ons、Add-ons Marketplace)。
  • back-end​: “The back-end is written in Java.” (バックエンドは Java で記述されています。)
  • canceled
  • CTRL+C​: ​キーの組み合わせ​を示すには、CTRL+C のようにプラス記号を使用します。
  • cURL
  • Database as a Service (DBaaS)​: 形容詞として使用する場合にのみハイフンを入れます。
  • Dev Center​: (Devcenter​ ではありません)
  • DevOps
  • distribution​: Linux ディストリビューションを指す場合、distro​ ではなく distribution​ を使用します。
  • e-commerce​: 単語先頭の大文字化についてタイトルのスタイルが適用される見出しでは E-Commerce​ を使用します。文の先頭では E-commerce​ を使用します。
  • email
  • front-end​: “The front-end is written in Java.” (フロントエンドは Java で記述されています。)
  • hard code, hard-coded​: 動詞または名詞の場合は 2 語で記述し、形容詞の場合はハイフンでつなぎます。
  • I/O​: 入出力を指す場合、IO​ ではなく I/O​ を使用します。
  • IoT​: The Internet of Things (モノのインターネット)
  • JAR file​: (Jar file​ ではありません)Java Archive (Java アーカイブ) の略です。
  • login, log in​: “login” は名詞、"log in" は動詞です。
  • macOS
  • Platform as a Service (PaaS)​: 形容詞として使用する場合にのみハイフンを入れます。例: ​Heroku is a Platform-as-a-Service vendor​. (Heroku は Platform-as-a-Service ベンダーです。)
  • setup, set up​: “setup” は名詞または形容詞です。"set up" は動詞句です。例: After you set up your portal, your setup is complete. (ポータルの設定が終われば、設定は完了です。)
  • sign up, signup​: “sign up” は動詞です。"sign-up" は形容詞または名詞です。signup は使用しないでください。
  • single sign-on​: シングルサインオン機能を指す場合は sign-on のようにハイフンを入れます。
  • third party, third-party​: ​3rd party​ とは記述しないでください。third party​ は名詞、third-party​ は形容詞です。例: The software came from a third party. (ソフトウェアはサードパーティ製です。)Third-party software (サードパーティソフトウェア)
  • unidle​: (un-idle​ ではありません)
  • Unix​: 1 文字目を大文字にします。すべて大文字 (UNIX) は商標にのみ使用します。
  • URL
  • utilize​: 使用を避けて use​ を優先します。
  • webhook​: (web hook​ または web-hook​ ではありません)
  • web server​: (webserver​ ではありません)

サードパーティリンクは禁止されていませんが、考慮事項がいくつかあります。

原則として、外部サイトへのリンクは避けてください。リンク先コンテンツの安全性、正確性、持続性を評価してください。

  • マルウェアによるハッキングや被害のおそれがない、信頼できるサイトでしょうか。
  • コンテンツは、すぐに更新または変更される可能性が高いものですか。
  • ダウンロードには直接リンクしないでください。代わりに、ダウンロード用のランディングページにリンクしてください。
  • 個人のブログ、Salesforce 以外のコミュニティサイト、頻繁に更新されるサイトにはリンクしないでください。

サードパーティのツール

Dev Center の記事で、サードパーティのツール、ライブラリ、またはフレームワークを紹介または推奨するのは、サポートされているデフォルトのテクノロジよりも明らかに効果的である場合に限定してください。

新しいテクノロジを導入するのが適切である場合は、そのテクノロジを Heroku プラットフォームに導入するメリットを根拠付ける記事の作成を検討してください。

その他のガイドライン

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