英語ドキュメント執筆ガイド
このガイドは、Inkiの英語ドキュメントを執筆する際の品質基準とベストプラクティスを提供します。目的
このガイドは、以下の特徴を持つ一貫性のある高品質な英語ドキュメントの維持を支援します:- 英語ネイティブスピーカーにとって自然に読める
- 明確で簡潔に伝わる
- 親しみやすく、近づきやすいトーン
- 確立された規約に従っている
対象読者
- ドキュメントを執筆・編集するAIエージェント(Claude)
- 英語ドキュメントに貢献する開発者
- ドキュメント品質をチェックするレビュワー
編集の一般原則
理解してから修正する。 これらの原則は言語に関係なく、すべてのドキュメント編集に適用されます。まず理解する
変更を加える前に:- ドキュメント全体を読む - 一部だけに集中しない
- 構造を理解する - セクション同士の関係性を把握する
- 目的を特定する - このドキュメントは何を達成しようとしているか?
- 関連ドキュメントを確認する - より広いドキュメント全体の中での位置づけを理解する
必要最小限の変更
必要な変更のみを行う:- 既存の構造を保持 - 本当に必要でない限り再構成しない
- コアコンテンツを維持 - すべてをゼロから書き直さない
- 具体的な改善に集中 - 個人の好みではなく、実際の問題に焦点を当てる
- 一貫性を維持 - 既存ドキュメントのスタイルとトーンに合わせる
何を変更すべきか
変更すべき:- 誤った情報
- 不明確な説明
- ぎこちない表現
- 規則に違反する句読点(例:em dash)
- 一貫性のない用語
- 全体的なドキュメント構造(本当に壊れていない限り)
- すでに明確で正しい内容
- すでに許容範囲内のスタイル選択
- うまく機能している情報の整理
編集アプローチの例
docs/en/getting-started/introduction.mdx を編集する場合: ✅ 良いアプローチ:- ファイル全体を読む
- 該当する場合は日本語版と比較する
- 具体的な問題を特定する(例:em dash、冗長な表現)
- 構造を保持しながらそれらの問題を修正する
- 変更を焦点を絞り、最小限に保つ
- すべてを自分の言葉で書き直す
- 個人の好みでセクションを再構成する
- すでに十分良いものを変更する
- 議論なしに新しいセクションを追加する
より大きな変更を行うべき時
以下の場合は、より大きな再構成が適切です:- ドキュメント構造が本当に混乱している
- 情報が間違った場所にある
- 内容に大きな欠落がある
- ユーザーが明示的に再構成を要求している
コア原則
英語ドキュメントを執筆する際は、以下の5つの原則に従います:1. 簡潔性(Conciseness)
意味を伝えるのに必要最小限の言葉を使う。 なぜ重要か:- 読みやすく理解しやすい
- 読者の時間を尊重する
- UI制約でより効果的
- 冗長な情報を削除する
- 不要な修飾語を削る(“in order to” → “to”)
- 他の場所で述べられている情報の繰り返しを避ける
2. 明確性(Clarity)
具体的で曖昧さのない言語を使う。 なぜ重要か:- 誤解を防ぐ
- ユーザーが正しい行動を取れるようにする
- サポート問い合わせを減らす
- 何が起こるかを具体的に述べる
- 具体的な動詞を使う
- 曖昧な用語を避ける
3. 自然さ(Natural Expression)
ネイティブ英語スピーカーが使う慣用句やフレーズを使う。 なぜ重要か:- プロフェッショナルで信頼できる印象
- 読みやすく快適
- ぎこちない翻訳を避けられる
- 日本語からの直訳を避ける
- 親しみやすいトーンのため短縮形を使う(it’ll, can’t, you’ll)
- 受動態より能動態を選ぶ
4. 一貫性(Consistency)
全体を通して同じ用語とスタイルを使う。 なぜ重要か:- ユーザーにとって学びやすい
- プロフェッショナルな外観
- メンテナンスしやすい
- “project” を一貫して使う(“project” や “workspace” と混在させない)
- “learning source” を一貫して使う(“training data” と混在させない)
- リスト内で一貫した動詞形を維持する
- 一貫した見出しスタイルを使う
- 用語について既存ドキュメントを確認する
- 主要な用語の用語集を作成する
- 類似機能には同じ表現を使う
5. ユーザーフレンドリー(User-Friendliness)
ユーザーの視点から書き、ベネフィットを強調する。 なぜ重要か:- より魅力的
- 価値提案がより明確
- より良いユーザーエクスペリエンス
- ユーザーができることや得られることに焦点を当てる
- “you” と “your” を使う
- 必要でない限り技術的な専門用語を避ける
句読点ルール
Em Dash (—) を避ける
節を分けるためにem dashを使わない。 代わりにピリオドを使う。シンプルな句読点を使う
基本的な句読点のみを使う:- ピリオド - 文の終わり
- カンマ - リストと節の区切り
- 疑問符 - 質問
- コロン - リストや説明の導入
短縮形を使う
短縮形はドキュメントを親しみやすくします:“e.g.,” を正しく使う
常に “e.g.” の後にカンマを含める:トーンとスタイル
会話的
マニュアルを書くのではなく、同僚に説明するように書く。アクション志向
動詞と能動態を使う。ベネフィット重視
機能が何をするかだけでなく、ユーザーが何を得るかを説明する。共通パターン
見出し
見出しは短く明確に:機能説明
形式:アクション + ベネフィット手順
命令形を使い、具体的に:リスト
項目の構造を並列に保つ:避けるべき表現
直訳
冗長な表現
堅苦しすぎる表現
実際の改善例
例1: Introduction
修正前:- 明確性のためプロダクト名を追加
- より簡潔な冒頭
- “the editor” を “your editor” に変更(よりパーソナル)
例2: Key Features
修正前:- Em dash (—) を削除、通常のダッシュ (-) を使用
- より自然な表現(“Complete” vs “End-to-end”)
- “brainstorming” は “ideation” より会話的
例3: Feature Descriptions
修正前:- “what to write next” は “continuations” より明確
- “your cursor” を削除(暗黙的)
例4: Instructions
修正前:- 明確性のため順序を変更(AIを主語に)
- 短縮形 “It’ll” を使用
- より簡潔(“for better suggestions” vs “to provide contextual suggestions”)
品質チェックリスト
ドキュメントを公開またはコミットする前に確認:- Em dash (—) を使用していない
- シンプルな句読点のみ(ピリオド、カンマ、疑問符)
- 適切な場所で短縮形を使用(can’t, it’ll, you’ll)
- “e.g.,” にカンマを含める
- 冗長な表現がない
- 能動態を使用
- ユーザーのベネフィットが明確
- 用語の一貫性
- 自然で会話的なトーン
- 明確性を失わずに簡潔
- すべての文に目的がある
このガイドを使用するタイミング
常に:- 新しい英語ドキュメントを書く時
- 日本語ドキュメントから翻訳する時
- 英語ドキュメントをレビューする時
- 既存の英語ドキュメントを更新する時
- ドキュメント構造を計画する時
- 用語を選択する時
- トーンを決定する時
- スタイルの疑問を解決する時
関連リソース
frontend/src/lib/i18n/- UIテキストの翻訳.claude/skills/i18n-translation/- 詳細なガイドラインを持つ翻訳スキルdocs/ja/- 日本語ドキュメント(ソース資料)
メンテナンス
このガイドは以下の場合に更新すべきです:- 新しいドキュメントパターンが現れた時
- 用語が変更された時
- スタイルの好みが進化した時
- 共通の問題が特定された時
