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

文体・文章構造について

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

記載内容について

主語や実施主体、対象や処理対象がわかる文章にすること
- 例えば「手動入力で保持」のような、曖昧な表現を避ける
現行仕様 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ファイルの末尾は空行で終わっていること

Back to top