tenzir-technical-writing

テクニカルライティング

Google の開発者向けドキュメント スタイルガイドに基づいて、明確で一貫性のある技術ドキュメントを作成します。

基本原則

• 巧みさより明確さを優先する：洗練された文章より、理解しやすい文章を優先します。
• 一貫性を保つ：ドキュメント全体でルールを一様に適用します。
• 読者を第一に考える：英語の習熟度がさまざまな開発者に向けて書きます。

文体とトーン

二人称を使う：読者に「あなた」と直接呼びかけます。

良い例：「config.yaml を編集すると、サーバーを設定できます。」 悪い例：「config.yaml を編集すると、サーバーを設定できます。」

能動態を使う：誰が操作を行うのかを明確にします。

良い例：「この関数はエラーコードを返します。」 悪い例：「エラーコードはこの関数によって返されます。」

親しみやすく、かつ専門的にする：スラング、専門用語、過度に堅苦しい表現を避け、自然な文章を書きます。「you're」「don't」「it's」のような一般的な短縮形を使い、くだけたトーンを保ちます。

避けること

• 専門用語や流行語：「活用する」「利用する」「相乗効果」
• 不要な前置き：「ご注意ください」「留意すべき点として」
• 感嘆符：本当に興奮を伝えたい場面に限って使います。
• 簡単だと思わせる表現：「単に」「ただ」「簡単に」（読者が苦労している場合に不快感を与えます）
• ラテン語の略語：「e.g.」ではなく「たとえば」、「i.e.」ではなく「つまり」と書きます。
• 方向を示す表現：「上／下」ではなく「前／後」とします。
• 擬人化した表現：ソフトウェアに人間の性質を持たせないでください（「システムが望む」「サーバーが考える」など）。
• 冠詞を省略すること：見出しでも「a」「an」「the」を必ず使います。

包摂的な言葉遣い

避ける表現	代わりに使う表現
blacklist/whitelist	denylist/allowlist、blocklist/safelist
master/slave	primary/replica、leader/follower
man-hours	person-hours
guys	everyone、folks、team
sanity check	quick check、coherence check

大文字の使い方

• 見出しはセンテンスケース：最初の語と固有名詞のみを大文字にします。
• 製品名：常に大文字表記を使います（Tenzir、Kubernetes、Docker）。
• 頭字語：標準的な大文字表記を使います（API、HTTP、JSON）。

見出し

• タスクの見出し：不定詞のみを使います（「インスタンスを作成する」）。
• 概念の見出し：名詞句を使います（「ユーザー認証」）。
• 階層：レベルを飛ばさないでください（h1 から h2 を飛ばして h3 にしない）。
• リンクを入れない：見出し内のハイパーリンクは避けます。

リスト

番号付きリスト：順番に行う手順や順序のある項目に使います。

箇条書きリスト：順序のない項目に使います。

リストのガイドライン：

• 完全な文の後にコロンを付けて導入します。
• 各項目は大文字で始めます。
• 各項目で並列構造を使います。
• 項目に動詞が含まれる場合、または完全な文の場合は、ピリオドで終えます。
• 1 項目だけのリストは使いません。

手順

構成：

1. 背景を説明してから始めます。
2. 各手順に番号を付けます。
3. 手順は命令形の動詞で始めます。
4. 操作の前に場所を示します。

ガイドライン：

• 「設定パネルで、保存 をクリックします。」（操作の前に場所を示す）
• 任意の手順は、冒頭に「任意：」と付けます。
• 複数の代替手段ではなく、実行可能な手順を 1 つ記載します。
• 手順では「お願いします」を使いません。

テキスト内のコード

次の要素にはコードフォント（バッククォート）を使います。

• コマンドラインの入力と出力
• ファイル名とパス
• クラス名、メソッド名、関数名
• キーワード、変数、パラメーター
• HTTP ステータスコードとメソッド

次の要素にはコードフォントを使いません。

• 製品名とサービス名
• ブラウザーで開く URL
• ドメイン名

文法：コード要素を活用させないでください。「POST のデータを送る」ではなく、「POST リクエストを送る」と書きます。

用語の選び方

避ける表現	代わりに使用する表現
aka	also known as、または括弧を使用する
allows you to	lets
config	configuration
admin	administrator
click on	click
check（チェックボックス）	select
uncheck	clear
higher/lower（バージョン）	later/earlier

書式

• UI 要素：太字（File > Save）
• ユーザー入力：文脈に応じてコードフォントまたは太字
• 新しい用語：初出時に斜体
• 強調：控えめに使用し、文の構成を変えることを優先します

リンク

• 文脈から切り離しても意味が通じる、説明的なリンクテキストを使用します
• 「ここをクリック」や「このページ」は避けます
• 良い例：「認証ガイドを参照してください。」
• 悪い例：「詳細についてはこちらをクリックしてください。」

参照するガイドラインの優先順位

スタイルに関する疑問が生じた場合は、次の順に参照してください。

1. プロジェクト固有のガイドライン
2. Google Developer Documentation Style Guide
3. Merriam-Webster（スペル）
4. Chicago Manual of Style（一般事項）
5. Microsoft Writing Style Guide（技術文書）