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

文体・文章構造について

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

記載内容について

• 主語や実施主体、対象や処理対象がわかる文章にすること
  • 例えば「手動入力で保持」のような、曖昧な表現を避ける
• 現行仕様 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のように表記する

修正時の対応

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

その他ルール

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