ja-technical-writing

公開する日本語の技術文書(チュートリアル・ハウツー・解説)を書く・直す・レビューするときに必ず参照する。表記(全角半角・数字・記号・カタカナ長音)・論理(用語導入・圧縮の禁止・根拠)・Geolonia社内の言葉遣いの3層で規則化してある。「技術文書」「ドキュメント品質」「textlint」「体言止め」と言われたら参照する。

SKILL.md

GitHub

ja-technical-writing

多くの読み手に向けた日本語の技術文書を書く・直す際の規則集である。 [[ja-text-communication]] がエージェント自身の発言・作業報告を律するのに対し、本skillは製品ドキュメント本文を対象にする。3つの層に分けてある。

  • 表記の層: 全角半角・数字・記号・カタカナ長音などの「見た目」の統一。textlintのような機械でも検出できる。
  • 論理の層: 用語の導入・圧縮の禁止・根拠の明示などの「意味の伝わり方」。機械では検出しにくく、書き手の判断が要る。
  • 社内の語: Geolonia固有の言葉遣いと、公開文書としての作法。

適用順序に迷ったら、まず論理の層(意味が壊れていないか)を確認し、次に表記の層(見た目の統一)を直す。表記だけ直して意味の欠落を放置しない。

表記の層(orthography)

出典: Microsoft Japanese Localization Style Guide(https://aka.ms/japanese-styleguide)を典拠として参照し、docs.geolonia.comの実情に合わせて我々の言葉で規則化した。原文の言い回しはそのまま転記していない(著作物ゆえ)。全体の趣旨を要約した参考資料であり、原文の代わりにはならない。

  • O1. 全角と半角が隣り合う箇所には半角スペースを入れる。 日本語の地の文と英数字(API キーのような表記)が接する境目に半角スペースを1つ挟む。ただし、句読点(。、)の直後・括弧やかぎ括弧の外側・疑問符と感嘆符が全角文の直後に来る場合はスペースを入れない。
  • O2. 数字は原則アラビア数字(半角)を使う。 「1つ」「3ヶ月」のように置き換え可能な数はアラビア数字にする。「もう一度」「四捨五入」のように数字部分だけを漢数字に戻すと不自然になる慣用句は、漢字表記のままでよい。
  • O3. 句読点・引用符・括弧の全角半角を使い分ける。 句点と読点は全角(。、)を使う。かぎ括弧「」は見出しや強調したい語に、半角の二重引用符はコード片や画面表示文字列を指すときに使う。丸括弧は原則半角。英数字の区切り(コロン・ハイフン・スラッシュ)は半角のまま、日本語の文中に置く。
  • O4. カタカナ語の長音(音引き「ー」)は文書内で統一する。 語尾が -er/-or/-ar のような伸ばす音で終わる外来語は、原則として長音符号を付ける(例: サーバー、コンピューター)。分野の慣用で長音を省く表記(例: サーバ)を使う場合は、その文書群全体で表記を揃える。混在させない。
  • O5. 外国語の固有名詞の区切りには中黒(・)を使う。 人名・地名など複合的なカタカナ語を並べるときに使う。
  • O6. 二重否定を避ける。 「〜されていない場合、安全ではありません」のような否定の重ねを、「〜されている場合に安全です」のような一つの肯定表現に言い換える。
  • O7. 冗長な動詞化を避ける。 「〜の実行を行います」のような名詞+「を行う」の言い回しは、素直に「〜します」に言い換えられないか確認する。ただし「インストールする」のようにカタカナ動詞として定着している語はそのままでよい。
  • O8. 体言止めは見出し・ラベル・キャプションなど短い要素に限る。 メニュー名やタイトルでは体言止め(名詞で言い切る形)が簡潔で読みやすい。しかし説明文(本文の地の文)で体言止めを使うと、誰が・何を・どうするのかという関係が曖昧になりやすい。本文では主語・目的語を省略しない、ですます調の文で書く。

論理の層(logic)

出典: [[ja-text-communication]](MIT License, mathbullet/skills, 取得コミット fe96c626b39abba47fad2d4a4ef738e8a27602b1)。同skillはエージェントの発言全般を対象とするが、製品ドキュメントの本文にもそのまま当てはまる条項が多い。適用可能な条項を以下に引く(番号は原典と共通)。原典が更新された場合はそちらを正とする。

用語の導入(A系列)

  • A1. 専門用語・略語は初出で定義する。
  • A2. 固有名詞(ツール名・製品名)は初出時に一言の位置づけを添える。
  • A5. 文書が変われば用語は再定義する。前の記事で説明済みでも、新しい記事では再導入する。

日本語表現(B系列)

  • B1. 英語術語は定着した日本語訳・カタカナの順で選ぶ。定訳の有無は推測せず確認する。
  • B3. 独自の造語・比喩・口語表現を避け、技術的な実体の言い換えを添えるか使わない。
  • B4. 事実として成立していない状態(未リリース・未検証)を、成立しているかのような言い回しで書かない。

圧縮の禁止(C系列)

  • C1. 一文一義。複数の手順・条件を一文に詰め込まない。
  • C2. 主語・目的語・動作主を省かない。体言止めや圧縮句で操作手順や設計判断を表現しない(表記の層のO8と対応する)。
  • C4. 見出し・キャプション・表のセルに未説明の圧縮表現を置かない。

参照と数量(D系列)

  • D1. 「この」「その」のような指示語より固有名(ページ名・変数名)を優先する。
  • D4. 数値には単位・分母・集計範囲を添える。

論理と文書構成(E系列)

  • E1. 手順や注意書きには理由を添える。理由を書けない場合は、その旨を明示する。
  • E4. 見出しと内容を一致させる。

根拠・事実性(F系列)

  • F3. 一次情報を優先する。コードやAPIの現在の挙動を確認してから書く(記憶や推測で仕様を語らない)。
  • F5. 現在の日付・バージョンと整合させる。CDNのバージョン番号やAPIの版数は実物を確認してから書く。

G系列(作業報告)・H系列(読者文脈の保持)はエージェントの対話向けの条項であり、製品ドキュメント本文には基本的に該当しない。

社内の語(house style)

  • 外部の出典を公開文書の本文で名指ししない。 「Microsoft Style Guideによれば」のように典拠を本文に書かない。規則を実務に落とし込んだ結果だけを自社の言葉で書く。内部の設計メモ(本skillのような)に出典を残すのは構わない。
  • 横棒(─・──)を多用しない。 日本語話者はあまり使わず、AIが書いた文章に見えやすい。句読点・括弧・かぎ括弧、または文の言い換えで代替する。
  • 製品名・ライブラリ名の表記は既存ページの多数派に合わせる。 例: 「Geolonia Maps」「embed」(小文字)「maps-suite」「maps-react」「GeoJSON」「MapLibre」。新しい記事を書く際に独自の表記を作らない。
  • チュートリアルの「段」番号のような既存の構成上の命名は、この skill の対象外とする。 表記や論理の修正はしてよいが、章構成・命名規則の変更は別途の設計判断であり、本skillの適用だけで変えてはならない。