ドキュメント作りにおけるルール整備 文体・文章構造について 本文は日本語の「だ・である」調を基本とすること 本文において、体言止めは使用しないこと 箇条書きによるリストアップ、表内の記載、見出しは例外とする 一文には原則として、一つの要件や判断を記載すること 一つの行や文に複数の論点を詰め込まず、改行または文章の分割を行うことで小さい文を積み上げ、表現すること 記載内容について 主語や実施主体、対象や処理対象がわかる文章にすること 例えば「手動入力で保持」のような、曖昧な表現を避ける 現行仕様 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ファイルの末尾は空行で終わっていること