ドキュメント作成スキル は何をしますか?
実際の人間が読みたいドキュメントを作成します。短く、平易に、誰かが実際に何かを達成しようとしていることに焦点を当てて書きます。
「機能Xのドキュメントを書く」ことが仕事ではありません。「誰かがXを使ってYをするのを助ける」ことが仕事です。
2つのフェーズで作業します。最初にストーリーを計画します。誰が読むのか、彼らが何を望んでいるのか、そして何ページにすべきかを決めます。その後、執筆に移ります。
計画は非公開ではありません。ユーザーは読者リストを見て、ページを書き始める前にトーンを選択する必要があります。
ドキュメントを見つける
→ 近隣のページを読む
→ フェーズ1: 読者 + ページ数
→ ペルソナゲート(チャットに読者リストを書き、停止する)
→ トーンゲート(チャットにトーンを書き、停止する) [ページ作成時]
→ simple-english と i-have-adhd をロードする [ページ作成時]
→ フェーズ2: 執筆
機能計画内のドキュメント影響リストは、ペルソナゲートを実行します。ただし、ページが実際に作成されるまではトーンゲートは実行せず、ライティングスキルのロードも行いません。
実行タイミング
ドキュメントはコードと一緒に出荷します。このスキルは、依頼があった時だけでなく、次の3つのタイミングで実行します。
- 誰かがドキュメントを依頼した時。ドキュメントを作成します。
- リポジトリ内の機能や変更を計画する時。計画が完了する前に、新しく作成するドキュメントと更新が必要なドキュメントをリストアップします。このドキュメント影響リストは、コード変更と同じく計画の一部です。各ページの読者を指定します。
- 実装を完了する時。作業が完了したと呼ぶ前に、それらのドキュメントを作成または更新します。動作の変更を行ったのにドキュメント変更を出荷しないことは、完了とは見なされません。
最終ページに必要なスキル
「simple-english」と「i-have-adhd」は必須です。これらは計画チャットではなく、ドキュメントページに適用されます。
ページコンテンツを作成する直前に両方をロードします。このハーネスにスキルツールがある場合はそれを使用します。ない場合は、各スキルのSKILL.mdをローカルのスキルディレクトリから読みます。これらのスキルの記憶からページを書かないでください。
どちらかのスキルが欠けている場合は、停止してユーザーに伝えてください。それらのスキルなしでページを作成しないでください。
それらの構成方法:
- このスキルは、ページの対象読者、ページ分割、問題→修正、示して語らない、履歴漏洩の禁止、禁止グリフ、近隣構造を担当します。
- 「simple-english」は文章を担当します。プラグマティックモードを使用します。ページ完了前に自己チェックを実行します。
- 「i-have-adhd」はページの形状を担当します: 最初に次のアクション、番号付きステップ、リストは5項目以内(必須と後回しに分割するか、ページを分割)、前置きなし、最後に目に見える成果。
このスキルから「i-have-adhd」をロードする場合、それをページにのみ適用します。セッション全体をADHDモードに切り替えないでください。「i-have-adhd」の永続化セクションはここでは適用されません。
まずドキュメントを見つける
何かを書く前に、ドキュメントがどこにあるかを見つけます。
- docsフォルダを探します。最初に
docs/を確認し、次にdocumentation/、content/docs/、site/、website/docs/を確認します。 - 見つからない場合は、ユーザーにドキュメントをどこに置くべきか尋ねてください。推測せず、思い付きでフォルダを作成しないでください。
- 新しいコンテンツが属する場所の近くにある2~3の既存ページを開いて読んでください。コピー、構造、フロントマターのフィールド、コンポーネントを確認します。トーンゲートの候補として、見られるトーンをメモします。まだ採用しないでください。
- サイトがすでに使用しているコンポーネント(ステップ、タブ、コールアウト、カード、アコーディオン、コードグループなど)をメモします。サイトによって異なります。
- それらのコンポーネントを再利用してストーリーを伝えます。サイトにステップコンポーネントがあれば、チュートリアルに使用します。タブがあれば、フレームワークのバリエーションに使用します。何もなければ、プレーンマークダウンを使用します。サイトにないコンポーネントを発明しないでください。
作成しようとしているページに似たページがない場合は、見つけられる最も近いページを読んでそれに合わせます。
「近隣に合わせる」の範囲と範囲外
近隣に合わせることは、コピー、構造、フロントマター、コンポーネントに関するものです。見出しが文の大文字小文字ルールに従っているか、セクションにどれだけの準備がされているか、どのコンポーネントがチュートリアルを担っているか、コードサンプルがどのように導入されているか、フロントマターのフィールドは何か。
これはトーンゲートの代わりにはなりません。近隣はデフォルトを示唆できますが、ユーザーに代わって回答することはできません。
また、近隣の悪い習慣をコピーする許可でもありません。禁止事項のすべてとこのスキルのすべてのルールは、周囲のページが何をしていようとも、あなたが書くコンテンツに適用されます。既存のページがemダッシュで埋め尽くされていても、さらに一つ追加する許可にはなりません。
つまり、このスキルが述べているルールについて、「他のページがそうしているから、私もそうする」と推論しないでください。既存のページがルールを破っていて、全体を改善すべきだと考える場合、それはユーザーに提起する別個のクリーンアップ作業であり、静かに違反に合わせて決着するものではありません。
フェーズ1: ストーリーを計画する
コンテンツを一言も書く前に行います。
- 誰がこれを読むか、そしてそれぞれが何を望んでいるかをリストアップします。React SPA上で構築している人、サーバーサイドレンダリングアプリを使っている人、簡単なデモだけを望む人、内部を拡張している人。最初の読者だけで止まらないでください。
- 読者ごとに1つのユーザーストーリーを書きます。「Xとして、Yをしたいので、Zできるように。」
- ストーリーをページに変換します。1つのジャーニーが1つのページです。異なるジャーニーは異なるページです。3つの実際のジャーニーがある機能は、1つの巨大なページではなく、おそらく短い概要を含む3つのページになります。
- すべての読者にパスがあることを確認します。ページがない読者は計画の穴です。彼らのためのページまたはルートを追加します。
ページ分割はこのステップから生まれます。省略しないでください。
ゲート: ペルソナを表示する
質問ツール(AskQuestion、ask_user_question、および類似の形式)は、そのペイロードをユーザーが読むチャットに表示しません。これらのツールだけを呼び出すターンは、このゲートを通過できません。ユーザーは見えないリストの確認を求められることになります。
ステップ4の後、通常のチャットメッセージを書きます。メッセージ本文は、質問ツールも呼び出す場合でも必須です。メッセージには以下が含まれます:
- 各読者を、ユーザーがスキャンできる短いブロックとして:
- 読者の名前
- 1つのユーザーストーリー: 「Xとして、Yをしたいので、Zできるように。」
- その読者のために書くページ
- 同じメッセージに書かれた1つの質問: 確認する、読者を削除する、または追加する。
質問ツールはオプションです。そのリストがすでにチャットメッセージにある場合にのみ呼び出します。ツールは短い選択肢のみを尋ねます(確認、削除、追加)。読者名、ストーリー、ページをツールの中に入れないでください。ツールがターンの唯一の出力になる場合は、呼び出さないでください。代わりにメッセージを書きます。
その後、1つのパスを選択します:
デフォルト: 停止。 このメッセージがターン全体です。ターンを終了します。ファイルを書き込まないでください。フェーズ2を開始しないでください。ユーザーが反論しない限り続行すると言わないでください。
待機をスキップ: 同じターン内で続行。 次のいずれかが当てはまる場合のみこのパスを使用します:
- この会話ですでにこのペルソナリストについてユーザーの確認を得ている。
- ユーザーが「妥当なデフォルトを使え」「とにかく書け」「質問するな」と言った。それでもこのターンでリストを表示してから続行します。
- 変更が小さなコピー編集(タイポ、壊れたリンク、コードフェンスの言語、事実の修正)である。新しいページ、新しいセクション、ジャーニーの書き直しはありません。
このパスでは、ターンを終了しないでください。リストを表示した後(または小さなコピー編集の場合はリストなしで)、次のステップに進みます。
これらはスキップではありません:
- 「読者は明白です。」
- 「ユーザーがドキュメントを依頼したので、質問を望んでいません。」
- 「すでに計画で名前を挙げました。」
- 「読者は一人だけです。」
- 「これは機能実装の一部なので、続けてください。」
- 「質問ツールがリストを表示します。」表示しません。リストはチャットに入れます。
ドキュメントを作成することは、このゲートが存在する理由です。それをスキップする理由ではありません。
少ない方が良い: 分割し、詰め込まない
何千もの単語を1つのページに強制しないでください。長いページは答えを隠します。
トピックに複数の側面がある場合、それぞれに独自の短いページを与え、リンクでつなぎます。読者は概要に着地し、必要な正確なものにクリックして移動します。
例。ツール割り込みの機能:
悪い例: 1つのページ
interrupts.md (概要 + 単純なケース + 複数の割り込み + カスタム、すべて詰め込み)
良い例: リンクされた小さなページのセット
interrupts/index.md それが何か、いつ使うか、リンク
interrupts/basic.md 1つの割り込み、最初から最後まで
interrupts/multiple.md フロー内の複数の割り込み
interrupts/custom.md 自分で作る
各ページは短く、1つのことを行います。概要がそれらをストーリーにまとめます。
ゲート: トーンを尋ねる
このゲートはフェーズ1とフェーズ2の間にあります。ページを書く前に実行します。フェーズ2の中に入れ子にしないでください。
近隣はデフォルトを示唆できますが、ユーザーに代わって回答することはできません。
通常のチャットメッセージを書きます。メッセージ本文は、質問ツールも呼び出す場合でも必須です。メッセージには以下が含まれます:
- 近隣ページから推測したトーンを1行で(どれほどフォーマルか、どれだけの準備があるか、二人称かどうか)。
- 同じメッセージに書かれた1つの質問: そのトーンを使う、よりカジュアルにする、よりフォーマルにする、またはユーザーが別のものを指定する。
質問ツールはオプションで、その行がチャットに入った後に来ます。ツールは短い選択肢のみを尋ねます。推測されたトーンだけをツールの中に入れないでください。ツールだけを呼び出すターンは、このゲートを通過できません。
その後、1つのパスを選択します:
デフォルト: 停止。 このメッセージがターン全体です。ターンを終了します。ページコンテンツを書かないでください。
待機をスキップ: 同じターン内で続行。 次のいずれかが当てはまる場合のみこのパスを使用します:
- この会話ですでにユーザーのトーン選択(「既存のページに合わせる」という明示的な指示を含む)を得ている。
- ユーザーが「妥当なデフォルトを使え」「とにかく書け」「質問するな」と言った。それでも推測されたトーンを1行で述べてから続行します。
- 小さなコピー編集、ペルソナゲートと同じ条件。
このパスでは、ターンを終了しないでください。トーンを述べた後(または小さなコピー編集の場合は質問なしで)、フェーズ2に進みます。
これらはスキップではありません:
- 「近隣からわかります。」
- 「サイトにはすでにボイスがあります。」
- 「リファレンスページではトーンは重要ではありません。」
- 「近隣に合わせて、後で言及します。」
フェーズ2: 人間らしく書く
ペルソナゲートを通過し、トーンゲートを通過し、simple-english と i-have-adhd がロードされるまで、ページコンテンツを書かないでください。
トーンゲートはこの見出しの上のものです。最初にそのゲートを実行します。次に2つのスキルをロードします。その後、執筆します。
読みやすさが何よりも優先される目標です。
- 消化しやすく保ちます。テキストの壁、巨大な段落は避けます。アイデアを小さな断片に分解します。仕事を果たす最小限の情報を提供します。
- 文は「simple-english」(プラグマティックモード)に従います。弱い代替をインライン化しないでください。
- マークダウンは軽く保ちます。リストは問題ありません。すべての行に太字見出しをつけるのは避けます。言葉にページを運ばせます。
- 派手なグリフよりもプレーンなASCIIと通常のキーボード文字を優先します。人がタイプする方法で書きます。
- 二人称、アクションを先に。読者が今持っているものと、最後に持つであろうものから始めます。「このガイドでは、私たちは探求します...」のような冒頭は避けます。ただ始めてください。
- 「i-have-adhd」でページを形作ります: 最初の行は読者が実行できること、複数ステップの作業は番号付き、5より長いリストは分割、ページは目に見える成果で終わります。
問題から始め、それから解決する
すべてのページは、APIの前に、読者が来た問題を彼ら自身の言葉で開きます。彼らが行き詰まっている状況を名前で示します。次に、1~2文で、機能がそれをどのように解決するかを述べます。その後にのみ、技術的な部分とコードに入ります。
問題を最初に見た読者は、正しいページにいるかどうかを数秒で知ることができます。最初にAPIシグネチャに当たった読者は、それが何のためにあるのかを逆算しなければなりません。
ハウツーの最初の行は(「i-have-adhd」からの)次のアクションです。問題は、彼らが正しいページにいることを知るために、依然として最初に来ます。
悪い例:
useInterrupts() を呼び出し、リゾルバを渡します。リゾルバはトランザクション内の保留中のアイテムごとに1回実行されます...
良い例:
ツールコールの中には、人間が「はい」と言うまで実行すべきでないものがあります: 送金、データ削除。割り込みはその決定のために実行を一時停止し、中断したところから再開します。以下は、承認の背後にツールをゲートする方法です:
[コード]
ガイドの順序は、問題、1行の修正、次にハウツー(ステップ、スニペット、API)です。問題は数文に留め、背景のエッセイにしないでください。コードが解決方法を示すので、最初に散文で解決策を説明しないでください。
示して、語らない
4段落で説明するよりも、1文とコードブロックで示す方が効果的です。読者は散文よりも差分やスニペットを素早く理解します。
悪い例:
configオブジェクトがmiddleware配列を受け入れ、各スロットの役割と順序の仕組みを説明する3段落。
良い例:
`middleware`配列にミドルウェアを追加します。順序は上から下に実行されます:
const app = createApp({
middleware: [auth, logging],
})
実行可能な良い例1つが、説明のページ1枚に勝ります。すべてのコードサンプルは、コピーしたら実行でき、想像でギャップを埋める必要がないものでなければなりません。
リストになるものはすべてリストにする
文が複数のアイテム、オプション、ストア、フラグ、ステップをカバーした瞬間に、それはリストになります。カンマとセミコロンで段落につなげないでください。箇条書きリストをスキャンする読者は、自分のアイテムを1秒で見つけます。段落では、全体を読まなければそれが自分に当てはまらないことを知ることができません。
兆候は、2つ以上のものを挙げてそれぞれについて何かを述べる文です。それを1つのアイテムにつき1つの箇条書きに切り分け、それぞれ1~2文にします。
悪い例:
各ストアは独立しています。必要なものだけを提供してください。チャットの場合: `messages`(トランスクリプト)、`runs`(ランライフサイクル)、`interrupts`(永続的な承認、`runs`が必要)、`metadata`(名前空間付きキー/バリューステート)。生成の場合: `generationRuns`(ランライフサイクル)、さらに`artifacts`と`blobs`で生成されたバイトを保持します。
良い例:
各ストアは独立しているので、必要なものだけを提供します。
チャットの場合:
- `messages`: トランスクリプト。
- `runs`: ランライフサイクル。
- `interrupts`: 永続的な承認。`runs`が必要。
- `metadata`: 名前空間付きキー/バリューステート。
生成の場合:
- `generationRuns`: ランライフサイクル。
- `artifacts`: 生成されたアーティファクト。
- `blobs`: 生成されたバイト。
リストはツリーや入れ子になった情報を表現するのにも適しています。複数レベルのリストを使用してください。閉じ括弧で終わる別の段落をインデントしないでください。
禁止事項
以下は絶対に禁止です:
- 履歴漏洩: 「前のセクションで見たように」「上記の」のようなフレーズは、読者が連続して読むと想定します。彼らはしません。読者は検索またはリンクからランディングします。すべてのページはスタンドアロンでなければなりません。同じページ内のセクション間でも、以前のセクションを知っていると想定せず、必要なコンテキストを繰り返すかリンクします。「上記」を使用する場合はいつでも、代わりにアンカーリンクを使用してください。
- 否定で始める: 「Xは認めない」は読者の心の中に「認める」という概念を作ります。「Xはブロックする」は読者に何が起こるかを教えます。
- 受動態: 「パラメータが渡される」は「パラメータを渡す」にします。「エラーがスローされる」は「エラーをスローする」にします。
- 「私たち」: このガイド、このセクション。読者はすでにここにいます。あなたと読者を「私たち」でまとめる必要はありません。
- 「単に」「ただ」「簡単に」「明らかに」「基本的に」: これらはガードレールの言葉です。読者がつまずいた時に気分を悪くさせます。
- 馬鹿げた例/比喩: フルーツ、動物、交通手段。実際の製品の概念を使用します。
- emダッシュ (—): 使用しないでください。カンマまたはピリオドでテキストをつないでください。長いダッシュは私的なメモや口調の変化を感じさせ、ドキュメントでは機能しません。既存のページがemダッシュを使用している場合、新しいコンテンツでは使用しないでください。
- ジョーク、駄洒落、自己言及: 読者はドキュメントで笑いを求めていません。
- 感謝: 読者がこのページにたどり着いたことへの感謝は不要です。時間を節約するのが感謝です。
編集のヒント
- アクションを前に出す: 「Xを設定することで、Yできます」は「Yするには、Xを設定します」にします。
- 前置詞で始めない: 「With X」で始まる文は、何についてなのかがわかるまで読者を保留にします。「Xを使用して、Yします」は「YするにはXを使用します」にします。
- 例でリンクする: 「その他のオプションについては、リファレンスを参照してください」と書く代わりに、読者が探しているであろうものを正確にリンクします。「rate limitを3に設定するには、speedリファレンスを参照してください」
- オプションの紹介: 「次のように設定できます」は「次のように設定します」にします。違いはありませんが、自信が伝わります。
- 明示的な数字: 「いくつかの」「複数の」「様々な」は使わないでください。数字や名前を挙げられますか?挙げられないなら、その文は必要ですか?
- 紹介不要: 「バリデーションを追加できるようになりました。それはデータが壊れないことを保証します。」は「バリデーションを追加して、データが壊れないことを保証します。」にします。
- より少ない前置詞: 前置詞は単語を追加します。「エラーのレートを制限する方法」は「エラーレートの制限」にします。前置詞のない所有格も検討します。「アプリの設定」は「アプリ設定」にします。
- 「彼ら」と「その」:
i-have-adhdは読者を「彼ら」とすることを好みます。読者が一人の場合でも、「ユーザー」よりも「彼ら」の方が自然です。 - 指示語: 「これ」「それ」は常にあいまいです。可能な限り避けて、名詞を使いましょう。
- あまりに多くの「してください」: 「設定してください」「設定したいと思うかもしれません」は「設定します」に置き換えます。
執筆フロー要約
フェーズ1: 計画
- ドキュメントフォルダを見つけ、近隣を読む
- 読者とユーザーストーリーをリストアップ
- ユーザーストーリーをページにマッピング
- すべての読者にパスがあることを確認する --- ペルソナゲート ---
- 読者リストを表示する
- 確認を待つ(または、許可されている場合は続行)
トーンゲート
- 近隣から推測されたトーンを述べる
- トーンの選択を確認する --- トーンゲート ---
- 「simple-english」と「i-have-adhd」をロードする
フェーズ2: 作成
- 各ページに問題から始める
- 解決策を示す。説明しない
- 「i-have-adhd」のルールを適用する: 次のアクション、番号付きステップ、リスト制限、最後の成果
- 禁止事項をチェックする: 履歴漏洩、否定、受動態、「私たち」、守護的な言葉
- ページを自己レビューする
- 必要に応じて「simple-english」の自己チェックを実行する