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

タイトル

記事のタイトルは、メタデータにtitleとlong_titleを指定して設定します。 タイトルは簡潔でわかりやすいものを使用してください。

• タイトルの長さ SEO対策の観点から、タイトルは15文字から30文字を目安に設定してください。(WSOFTDocs内の記事全体で末尾に| WSOFTDocsが追加されるため、実際の文字数は30文字から45文字程度になります)
• キーワードを含める タイトルには製品名やシナリオに関連するキーワードを含めてください。たとえば単に、「システムの概要」と表示するよりも、「WSNETの概要」としたほうが、ユーザーにとって何の記事かわかりやすくなります。
• 安易な誇大表現や煽りを避ける タイトルには【最新情報】や【期間限定】などの誇大表現・煽りを含めないでください。タイトルにノイズが含まれていると、読者が本当に欲しい情報かどうか選択するのが難しくなります。

記事の説明

記事の説明は、メタデータにsummaryを指定して設定します。 記事の説明は、ユーザーおよび検索エンジンのクローラーに伝えられ、記事がクリックされるかどうかの判断材料になります。

• 説明の長さ 記事の説明は120文字から160文字を目安に設定してください。あまりに説明が短い記事は、内容が薄いと思われる可能性があります。
• 内容の説明 記事で説明することや利点について、簡潔にまとめて説明してください。

ファイル名

ファイル名は、単に記事を管理するためのものだけでなく、Urlとしても使用します。ファイル名は以下の規則にしたがってつけてください。

• アルファベット小文字、数字とハイフンのみを使用する
• 単語や数値を区切るスペースや句読点の代わりにハイフンを使用する
• 動詞を使用する(start、developなど)
• 動詞は原形を使用する(原則過去形や進行形は使用しない)
• 定冠詞(a、theなど)やand、inなどの短い語句を使用しない

見出し

見出しは、Markdown中で#を複数回使用することで適用できます。

## これはH2見出しです
### これはH3見出しです

H1見出しは、記事の中でひとつのみにします。 この見出しは記事のタイトルを表示するために使用されるため、記事中でH1見出しは使用してはいけません。

H2見出しとH3、H4見出しは、記事の大きな要素を分割するために使用し、ユーザーや検索エンジンが記事の流れを理解するのに役立ちます。 1語や2語だけの短い見出しは避けてください。また、見出しはネストできます。

H5見出しよりも小さな見出しは使用しないでください。それらは通常のテキストより小さく表示される可能性があります。 また、そのような見出しが必要になる場合、記事の構造を見直すべきでしょう。

太字

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

例

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

斜体

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

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

例

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

コードスタイル

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

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

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

例

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

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

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

```cs
using Alice.Security;

byte[] salt = password_getSalt();

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

プレースホルダー

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

例

```sh
alice -r <ScriptPath>

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

alice -r \<ScriptPath\>

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

alice -r <ScriptPath>

。

見出しとリンクテキスト

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

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

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

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

例

++ctrl+alt+del++

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

Ctrl+Alt+Del

画像の代替テキスト

画像の代替テキストを設定することは、単にアクセシビリティの観点だけでなく、SEO対策の観点からも重要です。 画像の代替テキストを設定することでユーザーのみならず検索エンジンも画像を理解できるようになります。

• 代替テキストは、40字から150字程度で画像の内容を端的に説明してください。このとき「〜の画像」という文言は不要です。

わかりやすい文章

私たちプログラマーが書くドキュメントは、よく読みづらいと言われます。 その理由はたいてい以下のような理由です。

• 技術的正確性を追及するあまり、自分と同等以上の知識をもつ人にしか理解できない用語や前提条件がある
• 海外製の技術文書やIDEからのメッセージをよく読んでいるため、自然と機械翻訳のような文章になってしまう
• 記事内に画像やサンプルが少なく、または後回しにされることで読者が読むだけになってしまう

これらは、すべて私の担任の先生から教わった事柄です。すべての事項で共通していることは、読み手への意識の不足です。 担任の先生は、「いくら論理的に文章を書いても、読み手を意識しなければ理解できない」とおっしゃっていました。

もしあなたが記事の執筆にVS Codeを使用しているなら、テキスト校正くんという拡張機能が役に立ちます。この拡張機能は、誤字脱字やわかりづらい表現を知らせてくれるため、簡単に文章の品質を担保できます。まずは赤線が引かれない文章を目指しましょう。

また、わかりやすい文章を書くために、外部のスタイルガイドなどを参照して知識をつけるのも有効な手段です。以下に、外部の参考資料をいくつか示します。

• JTF日本語標準スタイルガイド（翻訳用）
• 正確な文章の書き方
• 誰がどう見てもそうとしか受取れない文章術（公開版）
• 誰にでもわかるSEのための文章術
• Technical Writing

WSOFTDocsにある記事も、なるべくわかりやすい文章になるように記事の見直しや校正に取り組んでいます。しかし、もともと他のサイトで公開されていた一部の記事はこの対象外になることをご了承ください。

例外

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

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