Skip to main content

英語ドキュメント執筆ガイド

このガイドは、Inkiの英語ドキュメントを執筆する際の品質基準とベストプラクティスを提供します。

目的

このガイドは、以下の特徴を持つ一貫性のある高品質な英語ドキュメントの維持を支援します:
  • 英語ネイティブスピーカーにとって自然に読める
  • 明確で簡潔に伝わる
  • 親しみやすく、近づきやすいトーン
  • 確立された規約に従っている

対象読者

  • ドキュメントを執筆・編集するAIエージェント(Claude)
  • 英語ドキュメントに貢献する開発者
  • ドキュメント品質をチェックするレビュワー

編集の一般原則

理解してから修正する。 これらの原則は言語に関係なく、すべてのドキュメント編集に適用されます。

まず理解する

変更を加える前に:
  1. ドキュメント全体を読む - 一部だけに集中しない
  2. 構造を理解する - セクション同士の関係性を把握する
  3. 目的を特定する - このドキュメントは何を達成しようとしているか?
  4. 関連ドキュメントを確認する - より広いドキュメント全体の中での位置づけを理解する

必要最小限の変更

必要な変更のみを行う:
  1. 既存の構造を保持 - 本当に必要でない限り再構成しない
  2. コアコンテンツを維持 - すべてをゼロから書き直さない
  3. 具体的な改善に集中 - 個人の好みではなく、実際の問題に焦点を当てる
  4. 一貫性を維持 - 既存ドキュメントのスタイルとトーンに合わせる

何を変更すべきか

変更すべき:
  • 誤った情報
  • 不明確な説明
  • ぎこちない表現
  • 規則に違反する句読点(例:em dash)
  • 一貫性のない用語
変更すべきでない:
  • 全体的なドキュメント構造(本当に壊れていない限り)
  • すでに明確で正しい内容
  • すでに許容範囲内のスタイル選択
  • うまく機能している情報の整理

編集アプローチの例

docs/en/getting-started/introduction.mdx を編集する場合: 良いアプローチ:
  1. ファイル全体を読む
  2. 該当する場合は日本語版と比較する
  3. 具体的な問題を特定する(例:em dash、冗長な表現)
  4. 構造を保持しながらそれらの問題を修正する
  5. 変更を焦点を絞り、最小限に保つ
悪いアプローチ:
  1. すべてを自分の言葉で書き直す
  2. 個人の好みでセクションを再構成する
  3. すでに十分良いものを変更する
  4. 議論なしに新しいセクションを追加する

より大きな変更を行うべき時

以下の場合は、より大きな再構成が適切です:
  • ドキュメント構造が本当に混乱している
  • 情報が間違った場所にある
  • 内容に大きな欠落がある
  • ユーザーが明示的に再構成を要求している
大きな変更は必ずチームと事前に議論してください。

コア原則

英語ドキュメントを執筆する際は、以下の5つの原則に従います:

1. 簡潔性(Conciseness)

意味を伝えるのに必要最小限の言葉を使う。 なぜ重要か:
  • 読みやすく理解しやすい
  • 読者の時間を尊重する
  • UI制約でより効果的
適用方法:
❌ "An AI-powered writing assistant that helps you with all types of writing"
✅ "An AI writing assistant that helps you write better, faster"

❌ "When you pause your cursor for 0.5 seconds"
✅ "Pause for half a second"

❌ "Select a category for the project you want to create"
✅ "Pick a category for your project"
ヒント:
  • 冗長な情報を削除する
  • 不要な修飾語を削る(“in order to” → “to”)
  • 他の場所で述べられている情報の繰り返しを避ける

2. 明確性(Clarity)

具体的で曖昧さのない言語を使う。 なぜ重要か:
  • 誤解を防ぐ
  • ユーザーが正しい行動を取れるようにする
  • サポート問い合わせを減らす
適用方法:
❌ "AI completion automatically activates"
✅ "AI completion turns on automatically"

❌ "Select text to get AI improvement suggestions"
✅ "Select text and AI will suggest improvements"
ヒント:
  • 何が起こるかを具体的に述べる
  • 具体的な動詞を使う
  • 曖昧な用語を避ける

3. 自然さ(Natural Expression)

ネイティブ英語スピーカーが使う慣用句やフレーズを使う。 なぜ重要か:
  • プロフェッショナルで信頼できる印象
  • 読みやすく快適
  • ぎこちない翻訳を避けられる
適用方法:
❌ "Learn the basics of using Inki"
✅ "Get started with Inki in minutes"

❌ "Writes in the same style as you"
✅ "AI will write in your style"

❌ "Enter a title and body text"
✅ "Enter a title and start typing"
ヒント:
  • 日本語からの直訳を避ける
  • 親しみやすいトーンのため短縮形を使う(it’ll, can’t, you’ll)
  • 受動態より能動態を選ぶ

4. 一貫性(Consistency)

全体を通して同じ用語とスタイルを使う。 なぜ重要か:
  • ユーザーにとって学びやすい
  • プロフェッショナルな外観
  • メンテナンスしやすい
適用方法:
  • “project” を一貫して使う(“project” や “workspace” と混在させない)
  • “learning source” を一貫して使う(“training data” と混在させない)
  • リスト内で一貫した動詞形を維持する
  • 一貫した見出しスタイルを使う
ヒント:
  • 用語について既存ドキュメントを確認する
  • 主要な用語の用語集を作成する
  • 類似機能には同じ表現を使う

5. ユーザーフレンドリー(User-Friendliness)

ユーザーの視点から書き、ベネフィットを強調する。 なぜ重要か:
  • より魅力的
  • 価値提案がより明確
  • より良いユーザーエクスペリエンス
適用方法:
❌ "System is processing"
✅ "Creating your project..."

❌ "Versatile use cases"
✅ "Built for any writing task"

❌ "End-to-end writing support"
✅ "Complete writing workflow"
ヒント:
  • ユーザーができることや得られることに焦点を当てる
  • “you” と “your” を使う
  • 必要でない限り技術的な専門用語を避ける

句読点ルール

Em Dash (—) を避ける

節を分けるためにem dashを使わない。 代わりにピリオドを使う。
❌ "AI works directly in your editor—no copy-pasting needed"
✅ "AI works directly in your editor. No copy-pasting needed."

❌ "Work seamlessly with AI—no switching between tools"
✅ "AI works right in your editor, no switching tools or copy-pasting"

シンプルな句読点を使う

基本的な句読点のみを使う:
  • ピリオド - 文の終わり
  • カンマ - リストと節の区切り
  • 疑問符 - 質問
  • コロン - リストや説明の導入

短縮形を使う

短縮形はドキュメントを親しみやすくします:
✅ can't, won't, don't, it'll, you'll, we'll
❌ cannot, will not, do not, it will, you will, we will(堅苦しすぎる)

“e.g.,” を正しく使う

常に “e.g.” の後にカンマを含める:
✅ "e.g., report, minutes..."
❌ "e.g. report, minutes..."

トーンとスタイル

会話的

マニュアルを書くのではなく、同僚に説明するように書く。
❌ "Upon pausing cursor movement, the system will generate suggestions"
✅ "Pause and AI suggests what to write next"

❌ "The user shall create a project prior to page creation"
✅ "Start by creating a project"

アクション志向

動詞と能動態を使う。
❌ "Projects can be used to organize documents"
✅ "Projects organize your documents"

❌ "Text completion suggestions are provided by AI"
✅ "AI suggests what to write next"

ベネフィット重視

機能が何をするかだけでなく、ユーザーが何を得るかを説明する。
❌ "Text completion feature"
✅ "Get suggestions as you type"

❌ "AI editing capability"
✅ "Polish and refine your text"

共通パターン

見出し

見出しは短く明確に:
✅ "What is Inki"
✅ "Create Your First Page"
✅ "Try AI Features"
✅ "Next Steps"

機能説明

形式:アクション + ベネフィット
✅ "Get suggestions as you type"
✅ "Polish and refine your text"
✅ "Generate text with instructions"
✅ "Find better ways to say things"

手順

命令形を使い、具体的に:
✅ "Click 'New Project' in the sidebar"
✅ "Pick a category (blog, email, proposal, etc.)"
✅ "Enter a name"

リスト

項目の構造を並列に保つ:
✅ すべて動詞で始まる:
   - Visit inki.so
   - Sign up with email or Google
   - Start writing right away

✅ すべて名詞句:
   - Sales proposals
   - Reports
   - Blog posts
   - Emails

避けるべき表現

直訳

❌ "Please input the title"
✅ "Enter a title"

❌ "It is possible to..."
✅ "You can..."

❌ "In the case of..."
✅ "When..." または "If..."

冗長な表現

❌ "in order to"
✅ "to"

❌ "at this point in time"
✅ "now"

❌ "due to the fact that"
✅ "because"

堅苦しすぎる表現

❌ "utilize"
✅ "use"

❌ "commence"
✅ "start"

❌ "subsequent to"
✅ "after"

実際の改善例

例1: Introduction

修正前:
An AI-powered writing assistant that helps you with all types of writing.
AI works directly in the editor.
修正後:
Inki is an AI writing assistant that helps you write better, faster.
AI works directly in your editor.
改善点:
  • 明確性のためプロダクト名を追加
  • より簡潔な冒頭
  • “the editor” を “your editor” に変更(よりパーソナル)

例2: Key Features

修正前:
- **AI works directly in the editor** - No copy & paste needed
- **End-to-end writing support** - From ideation to completion...
修正後:
- **AI works in your editor** - No switching tools or copy-pasting
- **Complete writing workflow** - From brainstorming to polishing...
改善点:
  • Em dash (—) を削除、通常のダッシュ (-) を使用
  • より自然な表現(“Complete” vs “End-to-end”)
  • “brainstorming” は “ideation” より会話的

例3: Feature Descriptions

修正前:
AI suggests continuations when you pause your cursor. Press `Tab` to accept.
修正後:
AI suggests what to write next when you pause. Press `Tab` to accept.
改善点:
  • “what to write next” は “continuations” より明確
  • “your cursor” を削除(暗黙的)

例4: Instructions

修正前:
When you create a project, AI learns your writing style and helps you
write consistently. The AI assistant will also reference your past documents
to provide contextual suggestions.
修正後:
AI will learn your writing style from this project and help you write
consistently. It'll also reference past documents for better suggestions.
改善点:
  • 明確性のため順序を変更(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/ - 日本語ドキュメント(ソース資料)

メンテナンス

このガイドは以下の場合に更新すべきです:
  • 新しいドキュメントパターンが現れた時
  • 用語が変更された時
  • スタイルの好みが進化した時
  • 共通の問題が特定された時
このガイドは実用的に保ち、実際のドキュメントからの実例に焦点を当ててください。