Heroku Dev Center のスタイルのガイドライン
この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。
最終更新日 2023年05月04日(木)
Table of Contents
Heroku のチームメンバーおよびアドオンプロバイダーは、Dev Center の記事を記述し、維持管理しています。Dev Center 以外のコントリビューターも、独自のドキュメントプロジェクトの規約を確立するための参考として、この記事を使用できます。
この記事には、Heroku Dev Center のスタイルガイドラインが含まれています。Heroku Dev Center の記事を記述または更新する場合は、一貫性のあるコンテンツをユーザーに提供するために、このガイドに従ってください。
Dev Center マークダウンの概要
Dev Center の記事では、GitHub フレーバーのマークダウンを使用します。構文の簡単な例を次に示します。
## セクションヘッダー
記事のトップレベルセクションには H2 ヘッダー (`##`) を使用してください。Dev Center では、これらのタイトルを解析して記事の目次を作成します。H1 ヘッダー (`#`) は記事内で使用しないでください。その他のテキストと[リンク](https://heroku.com/)の一部を示します。
![説明的なタイトル (画像に必要)](https://example.com/test.png)
### サブヘッダー
順序なしのリストを次に示します。
* 項目 1
* 項目 2
コマンドからの出力
```term
$ echo hi
hi
```
コード:
```ruby
puts "hello"
```
テーブル:
| A | B |
| --- | --- |
| 1 | 2 |
| 3 | 4 |
> note
> このような[スタイル付きの注意書き](#styled-notices)を含めることもできます。
太字
テキストを太字にするのは、UI 要素を参照するためにバックティックと併用する場合のみです。強調には、代わりに斜体を使用してください。
単語先頭の大文字化
すべてのタイトルと見出しで、タイトル形式で単語先頭を大文字化します。たとえば、次のようにします。
Heroku Postgres Maintenance Windows
次は悪い例です。
Heroku Postgres maintenance windows
辞書を使用して単語先頭の大文字化について適切に判断し、Salesforce スタイルガイドの単語先頭の大文字化ルールの概要を参照してください。
コードスニペット
ご想像のとおり、コードは Dev Center のドキュメントの重要な部分です。Dev Center では、Heroku でサポートされているすべての言語を強調する構文をサポートしています。
フェンスで囲むコードブロックの 1 行目は、3 つのバックティック ```
とオプションの言語識別子で始めます。
```ruby
puts "hello world"
```
This snippet renders as:
puts "hello world"
Heroku での主要言語の言語識別子は次のとおりです。
言語 | 識別子 |
---|---|
Ruby | ruby |
Node.js / JavaScript | javascript |
Python | python |
Java | java |
Scala | scala |
Clojure | clojure |
Objective-C | c |
PHP | php |
Go | go |
ターミナルコマンド
ターミナルコマンドと出力には、コードブロック識別子 term
を使用します。ターミナルコマンドの前にはプロンプトインジケーターの $
を付けます。
```term
$ heroku create
Creating blooming-water-4431... done
http://blooming-water-4431.herokuapp.com/ | git@heroku.com:blooming-water-4431.git
Git remote heroku added
```
このスニペットは次のようにレンダリングされます。
$ heroku create
Creating blooming-water-4431... done
http://blooming-water-4431.herokuapp.com/ | git@heroku.com:blooming-water-4431.git
Git remote heroku added
コンテキストと実行成功時の期待される結果がわかるよう、コマンドのサンプル出力を必ず示してください。わかりやすくするために、出力のうち、読者がコマンドを理解するために必要な部分のみを示してください。
Heroku CLI コマンド
多くの Heroku CLI コマンドでは、コマンドの実行対象の Heroku アプリを指定する --app
オプションをサポートしています。コードブロックで Heroku CLI コマンドを示すとき、コマンドでこのオプションがサポートされているときは、常に含めるようにしてください。
$ heroku config --app example-app
説明のために別の特定のアプリ名を記事ですでに使用している場合を除き、example-app
をアプリの名前として使用します。
インラインコード
インラインのファイル名、コマンド、およびコードはバックティックで囲みます。この書式設定により、`file.rb` が file.rb
とレンダリングされることが保証されます。
インラインで示すときは、コマンドラインのコマンドの前にプロンプト記号を付けないでください。
例の名前
Heroku アプリの名前
アプリに名前を付けるときは、アプリケーションの名前として example-app
を使用します。この場合、Heroku ホスト名は example-app.herokuapp.com
になります。
ドメイン
ドメインに名前を付けるときは、ドメイン名の例として www.example.com
を使用します。
ID
ID を含むコマンドを例示するときは、山かっこ (<id>
) を使用して ID を置き換えます。
シークレット
記事の中で、データベース接続文字列や AWS S3 キーなどのシークレットに言及することが必要な場合があります。
実際のシークレットは記載せず、シークレットの形式に沿った抽象的な文字列を作成します。次に例を示します。
次は良い例です。
postgres://user:password@ec2-1-2-3.compute-1.amazonaws.com:5432/databasename
それ以外の場合、抽象的な文字列の代わりに偽のシークレットを使用したほうが読者にとってわかりやすくなります。たとえば、次の例では、ユーザーがその形式を理解しやすいよう、抽象的な文字列の代わりに偽のベアラートークンを示しています。
term
curl -X POST https://hc-central.heroku.com/auth/example-app \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"
グラフィック
画像は、理解が難しい概念を簡明に伝え、テキストの大きなブロックからの視覚的な区切りを提供します。重要な概念を強調したり、長めの記事の構造をサポートしたりするために画像を使用してください。
ほとんどのグラフィックは一目瞭然です。画像に説明が必要な場合は、画像の前に新しい行で説明を記し、画像の下にはキャプションを追加しないでください。マークダウンでは、次のようにして画像を追加できます。
Some text description of this image:
![Image title](https://s3.amazonaws.com/bucket/image.jpg)
画像のタイトルは必ず角かっこ []
で囲んでください。
スクリーンショット
記事用にスクリーンショットを撮るときは、以下の手順に従ってください。
- 「本物」のように見えるデータを使用して、スクリーンショットを設定します。
- ブラウザウィンドウのサイズを 1024 x 768 以下に変更します。
- 使用しないスペースを最小限にし、将来的に時代遅れになりそうな要素はできるだけ排除します。
- スクリーンショットを撮ります。
- 必要に応じてコールアウトを追加します。
- 1 ポイントの黒の境界線を追加します。
- 次のガイドラインに合わせて画像を調整します。
- DPI: 200
- 幅 (ピクセル): 最大 800 ピクセル
- 幅 (インチ): 4 インチ
手順説明
ユーザーが特定の順序で手順を完了する必要がある場合は、番号を付けます。適切な句読点を含めて完全な文を使用します。
ほとんどの手順が 1 文か 2 文であるタスクの場合、次のような番号付きリストを作成します。
- Heroku Connect ダッシュボードで
Settings
(設定) タブをクリックします。 Import/Export Configuration
. (設定のインポート/エクスポート) をクリックします。Export
. (エクスポート) をクリックします。- 確認ウィンドウで
Export
(エクスポート) をクリックしてファイルをダウンロードします。
手順内の UI 要素の書式設定に関する注意事項は、「ユーザーインターフェースへの参照」を参照してください。
斜体
強調の斜体は多用しないでください。*
または _
で囲むとテキストを斜体にできます。次に例を示します。
*Text to italicize.*
これは、次のようにレンダリングされます。
斜体にするテキスト。
リンク
他の Dev Center 記事へのリンク
記事の slug (URL の最後の部分) を指定することによって他の Dev Center 記事にリンクします。次に示すのは、「dyno および Dyno Manager」の記事にリンクする方法です。
The [dyno manager](dynos) is responsible for keeping dynos running.
結果は次のとおりです。
Dyno Manager により、dyno の継続的な実行が維持されます。
同じ記事内のセクションへのリンク
次のようにして、同じ Dev Center 記事内のヘッダーにリンクします。
Here’s a link to the [Code Snippets](#code-snippets) section of this article.
結果は次のとおりです。
この記事のコードスニペットセクションへのリンクです。
異なる記事内のセクションへのリンク
次のようにして、別の Dev Center 記事内のヘッダーにリンクします。
Here’s a link to the [Install the Heroku CLI](heroku-cli#install-the-heroku-cli) section of [The Heroku CLI](heroku-cli) article.
結果は次のとおりです。
これは「Heroku CLI」記事の「Heroku CLI のインストール」セクションへのリンクです。
外部サイトへのリンク
外部サイトにリンクするときは、サイトの完全な URL を使用してください。
Here’s a link to the [Twelve-Factor App](https://12factor.net/).
結果は次のとおりです。
Twelve-Factor App へのリンクです。
リスト
手順が長すぎる場合を除き、手順説明には順序付きリストを使用します。
順序なしのリストは多用しないでください。箇条書きはネストしないでください。
文頭にリストの導入部を配置し、コロンを付けます。導入部が完全な文である場合は、最後をピリオド (句点) にします。
断片か完全な文かにかかわらず、各項目の最初の単語は先頭を大文字にします (英語の場合)。文の場合、最後をピリオド (句点) にします。たとえば、次のようになります。
使用している言語またはフレームワークがシードにどのように対応しているかを調査します。次に例を示します。
- Ruby gem Faker や JavaScript/Node ライブラリ Faker.js は偽のデータを生成します。
- Rails や Node.js の Sequelize などのライブラリにはシードを記述するための規則があります。
断片の場合、ピリオド (句点) を省略します。たとえば、次のようになります。
この記事のベストプラクティスでは、以下があることを想定しています。
- Node.js および npm がインストールされている
- 既存の Node.js アプリ
- 無料の Heroku アカウント
- Heroku CLI
ユーザーインターフェースへの参照
一部の Dev Center の記事では、(特に Dashboard、Data、または Connect 関連の) ユーザーインターフェースに言及します。次に例を示します。
プロビジョニングされてアプリケーションにアタッチされたアドオンを確認するには、Heroku Dashboard にアクセスします。アプリを表示している状態で、アプリの名前をクリックするか、
Resources
(リソース) タブをクリックします。
ユーザーインターフェース要素について記述するときは、UI コンポーネントの名前を ***`
と `***
の間に入れます。
前の例の書式設定は次のようになります。
**`Resources`**
この書式設定を使用して、一貫性を保ち、これらの要素が他の言語に翻訳されないようにします。
セクション
記事のトップレベルセクションには H2 ヘッダー (##
) を使用してください。Dev Center では、これらのタイトルを解析して記事の目次を作成します。H1 ヘッダー (#
) は記事内で使用しないでください。
スタイル付きの注意書き
Dev Center では、特別なスタイルの 3 種類の注意書きをサポートしています。
warning
note
callout
warning
の注意書きは、特定のアクションが破壊的または不可逆的であることを読者に知らせるために使用します。
>warning
>Removing an add-on destroys all associated data.
このスニペットは次のようにレンダリングされます。
アドオンを削除すると、関連付けられているデータがすべて破棄されます。
note
の注意書きは、読者がトピックを理解するために重要だが危険性はない情報を強調するために使用します。
>note
>While Heroku Git is convenient for deployment, it's not intended to be a stable git repository. Use [GitHub](http://github.com/), [GitLab](https://about.gitlab.com/), [BitBucket](https://bitbucket.org/), or another version control system to track your codebase.
このスニペットは次のようにレンダリングされます。
Heroku Git はデプロイのための便宜的なものであり、安定した Git リポジトリのためのものではありません。コードベースを追跡するには、GitHub 、GitLab、BitBucket などのバージョン管理システムを使用してください。
callout
の注意書きは、トピックに関連しているが読者の理解のために不可欠ではない情報を提示するために使用します。
>callout
>You can’t authenticate with the Heroku HTTPS Git endpoint using your Heroku email and password. The Heroku HTTPS Git endpoint only accepts API-key-based HTTP Basic authentication. Use an API key as described in this section.
このスニペットは次のようにレンダリングされます。
Heroku メールとパスワードを使用して、Heroku HTTPS Git エンドポイントで認証することはできません。Heroku HTTPS Git エンドポイントは、API キーベースの HTTP Basic 認証のみを受け入れます。このセクションでの説明どおり、API キーを使用してください。
目次の構造
Dev Center では、記事の h2
(Markdown では ##
) 要素からその目次を自動的に生成します。
次のヘッダーのセットは、Header 1
と Header 2
を含む目次になります。
## Header 1
### Header 1.1
## Header 2
記事のトップレベルのヘッダーが、記事の内容の概略を正しく 示していることを確認してください。
商標、ブランド名、機能名
“Heroku” のように単語の先頭を大文字にします。URL を参照するときは “heroku.com” を使用します。
Heroku のトレードマークは固有形容詞です。スペルや構造を変更しないでください。たとえば “Heroku’s” や “Heroku-ish” を使用しないでください。
“Salesforce organization” ではなく “Salesforce org” を使用します (英語の場合)。
製品のブランド名は単語の先頭を大文字にして、商標を他の単語と区別します。以下に例を示します。
- Apache Kafka for Heroku
- Heroku Add-ons
- Heroku Buildpacks
- Heroku Buttons
- Heroku CI
- Heroku CLI
- Heroku Connect
- Heroku Dev Center
- Heroku Dynos
- Heroku Elements Marketplace
- Heroku Enterprise
- Heroku Pipelines
- Heroku Postgres
- Heroku Private Space
- Heroku Shield
- Heroku Data for Redis および Heroku Shield for Redis
- Salesforce Connect
Heroku の製品または機能であることが文脈から明らかな場合、"Heroku" を省略できます。
機能名はブランド名である場合にのみ単語の先頭を大文字にしてください。マーケティングキャンペーンの対象である場合は、ブランド名ではない機能名について単語の先頭を大文字にすることも推奨されます。
他社が所有する商標について言及するときは、各社の商標ガイドラインに従ってください。
その他のガイドライン
この記事には、Heroku Dev Center のスタイルガイドラインが含まれています。記事を記述するときは、表現と文体およびコンテンツのガイドラインにも従う必要があります。詳細は、「Dev Center の記事の記述」を参照してください。