目次

テキストの書式設定に関する指針

テキスト要素の太字、斜体およびコードスタイル、キースタイルは、一貫性を保って適切に使用することで読みやすさを向上させ、誤解を避けることができます。

たい | 2023-09-25

太字

メニューの選択肢、ウィンドウの名前、入力フィールド名などのUI要素には太字を使用します。 Markdownで太字を表現するには、対象の文字列を**で囲みます。

例

  • 正:メインウィンドウで、ハンバーガーメニューをクリックして、「ファイル」>「名前をつけて保存」 の順に選択します。
  • 誤:メインウィンドウで、ハンバーガーメニューをクリックして、「ファイル」>「名前をつけて保存」の順に選択します。
  • 誤:メインウィンドウで、ハンバーガーメニューをクリックして、「ファイル」>「名前をつけて保存」の順に選択肢ます。

斜体

次のような場合は、斜体を使用します。Markdownで斜体を表現するには、対象の文字列を*で囲みます。

  • 定義または説明で出てくる新しい用語
  • ファイル名、ディレクトリ名、パス
  • ユーザー入力（キー表現を使用する場合を除きます）

例

  • 正:AlicePackageは、プログラムのスクリプト、リソース、ライブラリやパッケージを含むAliceModelで実行できるアプリパッケージ形式です。
  • 誤:AlicePackageは、プログラムのスクリプト、リソース、ライブラリやパッケージを含むAliceModelで実行できるアプリパッケージ形式です。

コードスタイル

次の場合は、コードスタイルを使用します。

  • 関数名、変数名などのプログラム
  • SQLコマンド
  • コマンドラインコマンド
  • データベースのテーブル名や列名
  • クリック可能にしないURL

コードスタイルは、文中で使用するために"`"で囲むか、複数の行にまたがるコードブロックを使用するために"```"で私用できます。

例

  • 正:AliceScriptでは、print(string text);という関数を使用して標準出力にテキストを書き込みます。

  • 正:AliceScriptでは、print(string text);という関数を使用して標準出力にテキストを書き込みます。

  • 正:AliceScriptではpassword_salt関数で簡単にソルトを生成できます。

Markdown
```cs
using Alice.Security;

byte[] salt = password_salt();
  • 誤:byte[] salt = Alice.Security.password_salt();のように実行するだけで簡単にソルトを生成できます。

プレースホルダー

入力文字列の一部をユーザーが任意の値で置換する必要がある場合は、山かっこ（<>）で囲こみその中に説明を記述します。

例

Markdown
```sh
alice -r <ScriptPath>

または、バックスラッシュ文字（\）を使用して、山かっこ文字をエスケープして私用できます。必要なのは右山かっこに対するエスケープ（>）です。レンダリングされた後のHTMLでは、閲覧者にエスケープ文字は表示されません。

Markdown
alice -r \<ScriptPath\>

これは次のようにレンダリングされます。

alice -r <ScriptPath>

プレースホルダーの告知

プレースホルダーを使用する前のテキストで、括弧内のテキストを削除して実際の値に置き換える必要があることを閲覧者に説明しましょう。

注意事項

角かっこが正しくエスケープされていない場合またはテキストがコードブロック内にない場合、角かっこはそのままHTMLにレンダリングされる恐れがあります。このような記事の投稿または変更は、却下されるか、PullRequestで変更を提案します。

執筆したコンテンツが失われないようにするためにも、上の説明に従って、コードブロックの中に記述するか、エスケープ文字を使用してください。

見出しとリンクテキスト

太字や斜体などのスタイルは、見出しやリンクのテキストに使用しないでください。

ユーザーは、標準のリンクテキストを頼りに、テキスト要素をクリック可能なリンクとして認識します。たとえば、リンクを斜体としてスタイリングすると、テキストがリンクであるという事実がわかりにくくなります。見出しには独自のスタイルがあって、異なるスタイルを混在させると、見た目が悪くなります。

キー入力とキーボードショートカット

キーまたはキーボートショートカットを記述する場合、++で囲み、同時に入力するキーをつなげるには、+でつなぎます。キーの名前にはすべて小文字を使用します。

例

Markdown
++ctrl+alt+del++

これは次のようにレンダリングされます。

Ctrl+Alt+Del

例外

この指針は、厳格なルールではありません。当然例外もあります。読みやすさが損なわれる場合は、別のスタイルを使用してください。たとえば、大部分がコード要素の表の場合、すべてにコードスタイルを使用すると、非常に見ずらくなるかもしれません。このような場合、太字のスタイルを使用することも有力な選択肢になりえます。

大切なのは、その記事においてもっとも適切であると考えられるスタイルを使用することです。しかし、たとえあなたが適切だと考えたスタイルがもっとも適切なものではなかったとしても、誰も非難するべきではありません。必要な場合はIssueを立てて議論することもできます。