Japanese Technical Docs Writer

Japanese Technical Docs Writer

概要

このスキルは、日本語技術文書を執筆する際に以下の支援を提供します：

1. markdown のフォーマットを満たしているかチェック
2. textlintによる自動校正
3. 自動修正できない問題の特定と改善提案
4. 文章の自然さや読みやすさの向上

使用方法

/​japanese-technical-docs-writer [ファイルパス]

実行フロー

1. markdown フォーマットチェックフェーズ

• frontmatter に必須項目の name が含まれているか
• header が適切に設定されているか
• その他、markdown, mdx に記載できない記法が使われていないか、表示が崩れるような設定がないか

2. 文章作成・編集フェーズ

• 指定されたファイルの内容を確認
• 必要に応じて新規作成または既存ファイルの編集
• 技術文書として適切な日本語で執筆

3. textlint自動校正フェーズ

• pnpm textlint:fix を実行して自動修正可能な問題を解決
• 修正前後の差分を確認
• 自動修正された内容をユーザーに報告

4. 手動レビューフェーズ

• pnpm textlint を再実行して残存する問題を確認
• textlintで検出できない以下の問題をチェック：
  • 文章の論理的な流れ
  • 専門用語の統一性
  • 読み手を考慮した説明の充実度
  • カタカナ表記の一貫性（例：ユーザー/ユーザ）
  • 英数字と日本語の間のスペース
• 修正後、再度 pnpm textlint を実行して、textlint によるチェックがパスすることを確認

5. 改善提案フェーズ

• 検出された問題に対する具体的な修正案を提示
• 修正理由と技術文書としての品質向上ポイントを説明
• ユーザーの承認を得て修正を適用

チェック項目

textlintによる自動チェック（preset-ja-technical-writing）

• 一文の長さ（100文字以内を推奨）
• 読点の数（一文に4個まで）
• 連続する漢字の数（6文字まで）
• 助詞の連続使用
• 二重否定の回避
• ら抜き言葉の修正
• 文末の句点の統一
• 同じ接続詞の連続使用

手動チェック項目

• 用語の統一性

  • 送り仮名の統一（例：「取り組み」vs「取組み」）
  • カタカナ語末の長音符号（例：「サーバー」vs「サーバ」）
  • 英語表記とカタカナ表記の使い分け

• 文章構造

  • 見出しの階層構造の適切性
  • 段落の長さと区切りの適切性
  • 箇条書きの使用タイミング

• 技術文書特有の表現

  • 主語の明確化
  • 能動態と受動態の適切な使い分け
  • 断定的な表現と推測的な表現の使い分け

• 読みやすさ

  • 専門用語への初出時の説明
  • 略語の定義
  • 図表への適切な参照

出力フォーマット

修正作業完了後、以下の形式でレポートを提供：

## 📝 日本語技術文書校正レポート

### ✅ textlintによる自動修正
- [修正数] 件の問題を自動修正しました
- 主な修正内容：
  - [修正タイプ]: [具体例]

### ⚠️ 手動修正が必要な項目
1. **[問題の種類]**
   - 該当箇所：「[原文]」
   - 修正案：「[修正案]」
   - 理由：[修正理由]

### 💡 品質向上のための提案
- [提案内容]

### 📊 文書統計
- 総文字数：[数値]
- 平均文長：[数値]文字
- textlintスコア：[合格/要改善]

実行例

# 新規ドキュメント作成
/​japanese-technical-writer create src/​content/​docs/​guides/​setup.md

# 既存ドキュメントの改善
/​japanese-technical-writer src/​content/​docs/​potz/​index.md

注意事項

• textlintの設定（.textlintrc.json）はプロジェクトの方針に従います
• 技術用語や固有名詞は文脈から判断して適切に処理します
• 英語のコード例やコマンドは校正対象外とします
• マークダウンの構文は保持しながら日本語部分のみを校正します

依存関係

• textlint
• textlint-rule-preset-ja-technical-writing
• pnpm（パッケージマネージャー）

更新履歴

• 2025-12-10: 初版作成