writing-user-docs について
アプリやライブラリの利用者向け文書を作成するためのライティングスキルです。平易な表現、ユーザーの目的に沿った構成、観察できる動作の説明、失敗時の案内を重視します。
主な機能
- 01直接的で平易な表現
- 02ユーザーの目的に沿ったページ構成
- 03内部実装より観察可能な動作を優先
- 04エラーと破壊的操作の警告を記載
- 05草稿の明瞭さと網羅性を確認
活用シーン
- 01アプリ利用者向けヘルプページの作成
- 02ライブラリ開発者向け導入・利用ガイドの執筆
- 03トラブルシューティング手順の整理
- 04公開前の文書レビュー
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/writing-user-docsを入力して読み込まれたか確認します。
詳細
ユーザー向けドキュメント
ツールを作った人ではなく、使う人に向けて書きます。
「ユーザー」とは、そのツールを使う人のことです。アプリならエンドユーザー、ライブラリならインストールする開発者です。いずれの場合も、ユーザーはツールを実装する人ではありません。ドキュメントもそれを踏まえて書きます。
文体
日常的な英語を使います。隣に座っている同僚に説明するような言葉遣いです。堅苦しい表現は権威を高めず、距離と言葉を増やすだけです。
- 二人称、能動態、現在形を使います。 「［保存］をタップします」と書き、「［保存］ボタンをタップしてください」や「ユーザーはその後、保存できるようになります」とは書きません。
- 「just」「simply」「easy」「obviously」は使いません。 問題なく動くときは何の役にも立たず、動かないときには嘲笑のように受け取られます。
- 宣伝文句のような形容詞は使いません。 「パワフル」「シームレス」「堅牢」「直感的」などは、書き手が製品を称賛しているだけです。読者は作業の途中であり、そんなことは気にしていません。
- 概念ごとに用語を一つだけ使い、UI の表記に合わせます。 ボタンに Workspace と書かれているなら、ドキュメントでも「プロジェクト」や「チームスペース」とは書きません。語彙を使い分けるのは良い文章ですが、ドキュメントでは良くありません。同義語を使うたびに、新しい概念だと受け取られます。
範囲：何を書くか
読者がツールを使うために必要なことだけを書きます。基本的に、不要なことは書きません。
実装の詳細は含めません。 データベース、キュー、フレームワーク、アルゴリズムの名称、内部サービス、リリースまでに必要だったリファクタリングなどは書きません。「技術的かどうか」ではなく、**「これを知らないと読者が驚いたり、誤った判断をしたりするか」**を基準にします。
たとえ技術的な内容でも、読者から見える動作はこの基準を満たすため、ドキュメントに含めます。レート制限、オフライン時の動作、同期されるデータとそのタイミング、ファイルの保存場所、競合時の動作、再インストール後も残るデータなどです。そうした動作を実現する仕組みは書きません。
簡潔にするとは、短くすることではなく、無駄をなくすことです。 すべての文に役割を持たせます。トラブルシューティングの説明も、無駄がなければ十分に詳しくても簡潔です。一方、2 行しかないページでも、1 行が歓迎のあいさつなら冗長です。前置き、見出しの言い換え、「この記事では～を学びます」といった文は削ります。
構成
- 機能や画面ではなく、ユーザーの目的ごとに構成します。 見出しには「チーム外の人とレポートを共有する」のように、ユーザーがしたいことを書きます。「共有モジュール」のような名詞は使いません。
- まず結果を示し、その後に手順を書きます。 読者は手順 1 に進む前に、目的に合ったページかどうかを確認する必要があります。
- 前提条件や制限は冒頭に書きます。 必要なプラン、権限、プラットフォーム、ファイルサイズの上限などです。手順 6 で初めて行き詰まるのが、最悪のタイミングです。
- 1 ページで 1 つの疑問に答え、単独で読めるようにします。 多くの読者は検索結果やディープリンクからアクセスし、最初のページから順に読みません。前のページを読んでいるとは考えず、必要な場合はリンクします。
- 手順を 1 つ選びます。 3 つの方法があるなら、推奨する方法を説明します。別の方法は最後に短く記載するか、記載しません。
想定どおりに進まない場合も説明する
ここは最も見落とされやすい一方で、読者が実際に検索する内容です。
- 失敗するケースを説明します：エラーに表示される内容、原因、次にすべきことを記載します。
- ユーザーがその機能にできると予想しがちなことでも、実際にはできない場合は明記します。 サポートへの問い合わせより効率的です。
- データを破壊する操作の警告は、操作の前に記載し、後には記載しません。 警告は、対象の手順より前に置きます。
ドキュメントの劣化を防ぐ
- 実際にありそうなデータを使った例を示します。
foo、test123、Lorem ipsum は使いません。例はコピーしてそのまま使え、表示した結果と同じ結果になるようにします。 - 時間の経過で意味が変わる表現は使いません。 「新しい」「最近」「現在」「近日公開」などは、いつの間にか古くなります。ロードマップの約束も同様です。
- すべての手順を文字どおりに実行して確認します。 書かれたとおりに進めても完了できないなら、問題があるのは読者ではなくドキュメントです。
公開前に確認すること
次の点だけに注目して、原稿を一度読み直します。
- 読者が作業を完了するのに不要な内容はありませんか？ → 削除します。
- 内部の仕組みに関する説明はありませんか？ → 動作に関わる場合を除き、削除します。
- 声に出して読みづらい文はありませんか？ → 書き直します。
- 問題が起きた場合の対処方法は説明されていますか？