# ドキュメント作りにおけるルール整備

### 文体・文章構造について
- 本文は日本語の「だ・である」調を基本とすること
- 本文において、体言止めは使用しないこと
  - 箇条書きによるリストアップ、表内の記載、見出しは例外とする
- 一文には原則として、一つの要件や判断を記載すること
- 一つの行や文に複数の論点を詰め込まず、改行または文章の分割を行うことで小さい文を積み上げ、表現すること

### 記載内容について
- 主語や実施主体、対象や処理対象がわかる文章にすること
  - 例えば「手動入力で保持」のような、曖昧な表現を避ける
- 現行仕様 or 移行後の要件 or 将来構想を区別して記載すること
- ❗️事実と想定、合意事項と提案など **扱いの異なる情報** をしっかり区別すること
- 必須要件は「〜する」「〜しない」など、要否を判断できる表現にすること
- 「適宜」「必要に応じて」「可能な限り」などの曖昧な表現は使用を避け、どうしても使用する場合は条件や判断者を記載すること


### Markdown 記法について
- 本文において、強調記法(`**...**)`を多用しないこと
  - 使用する場合は**短い項目名**や**ラベル**に限定し、文章・事実・値・状態の強調には使用しないこと
  - ❗️ひとかたまりのテキストであることを示すために、強調記法を使用しないこと
  - 強調記法については、多用すると強調したい部分が強調されなくなってしまうため、一文につき一か所だけを使用することを目安とする
- `**項目の概要**: 項目の詳細` という表現の使用を認めるが、下記に注意すること
  - 箇条書きの階層表現により概要と詳細を表現できる場合には、箇条書きを優先して使用すること
- 番号付きリストについて、 Markdown の表形式で記載した方が読みやすくなる場合があるため、表形式での記載も検討すること
  - 手順に「番号・項目名・詳細」が並ぶ場合などは、表形式が望ましい
- Markdown のプレビューも合わせて確認し、書式が崩れていないことを確認すること
  - 具体的には、表が崩れている、不要な水平線がある、意図しない形で見出し表現になっているなど

### 本文における記号の使用について
- ❗️**読者に解釈を委ねるような記号・表現**が使用されていないこと
  - 具体的には「X→Yマッピング」といった抽象的すぎる記載を避け、「XからYへの機能マッピング」といった具体的な表現を使用する
- 箇条書きリストの導入文の末尾にコロン`:`は使用せず、通常の文章および句点を使用すること
- 必要に応じて、強調記法（`**...**`）ではなくかぎ括弧`「...」`により強調を行うことを認める

### 用語・キーワードの使用について
- 全体を通して、表記揺れがないこと（`ユーザ` vs `ユーザー` や、`Testing` vs `testing`など）
  - 英大文字・英小文字の違いや、半角スペースありなしなどにも留意する
- 製品の正式名称、コード、パラメータ名、ファイルパス、URL、引用文に含まれるスペースは、機械的な置換を行わないこと
- ❗️製品固有のキーワードについて、説明もなく突然現れたキーワードがないこと
- 製品固有のキーワードについて、表記間違いが存在しないこと 

### 文章の半角スペースの取り扱い
- 「英単語または英語の固有名詞」と「日本語」の間には、半角スペースを1ついれること
- 英略語と日本語の間には、半角スペースを入れないこと
  - 英略語とは、`AWS` / `GCP` / `MQ` など、全大文字で表記する略称を指す
- 複数の英略語で構成される正式名称内のスペースは維持すること（`AWS IAM`など）
- 数値、数量を表す接頭辞、単位および日本語の間には、半角スペースを入れないこと
  - `1,234 km` ではなく、`1,234km`のように表記する
 
| 内容 | 半角スペース | 記載例 |
|-|-|-|
|英単語または英語の固有名詞 と 日本語 の間|入れる|`Web アプリケーション` / `Python コード`|
|英略語 と 日本語の間|入れない|`API認証` / `SSH接続` / `AWSアカウント`|
|複数の英略語で構成される、正式名称内のスペース|入れる|`REST API認証` / `AWS IAMロール`|
|数値、数量を表す接頭辞、単位 と 日本語 の間|入れない|`2環境` / `約80%` / `2027年3月` / `1,234km`|

### 修正時の対応
- 単語の表記揺れに関する指摘を受けた際、指摘箇所だけでなくファイルを横断的に修正できていること
- ファイル名や章番号を変更した場合は、目次だけでなく本文リンクや参照情報なども同時に更新すること

### その他ルール
- 行末に不要な空白または全角空白を残さないこと
- インデントにはタブを使用せず、半角空白を使用すること
- 見出しの末尾に句点、コロンなどの不要な記号をつけないこと
- Markdownファイルの末尾は空行で終わっていること