docs-write

ドキュメント作成スキル

@./../_shared/metabase-style-guide.md

ドキュメントを作成するとき

まずここから

1. これは誰向けですか？ 読者に合わせて複雑さを調整します。難しいことを過度に単純化せず、簡単なことを過度に複雑にしないでください。
2. その読者には何が必要ですか？ 答えに素早くたどり着けるようにします。必要以上にドキュメントの中に長くとどまりたい人はいません。
3. あなた自身は何に苦労しましたか？ 学ぶときに抱いた、よくある疑問は何ですか？ それに答えてください（疑問文をそのまま載せるのではなく）。

作成プロセス

下書き:

• 同僚に話すように手順や説明を書き出します
• 何をするかを先に示し、その後に理由を説明します
• 要点を述べる見出しを使います。「ユーザーを追加する前に SAML を設定する」であって、「SAML 設定のタイミング」ではありません

編集:

• 声に出して読みます。自分が話しているように聞こえますか？ 堅苦しすぎるなら、簡潔にします
• 読者に直接役立たないものは削ります
• 各段落に明確な目的が1つあるか確認します
• 例が実際に動作するか検証します（エラーになる例を載せないでください）

推敲:

• リンクは内容がわかるテキストにします（「ここ」は使わない）
• バッククォートはコードや変数にのみ、UI 要素には 太字 を使います
• アメリカ英語の綴り、シリアルコンマを使います
• 画像は最小限にし、範囲を絞ります

フォーマット:

• 編集後、ファイルに対して prettier を実行します: bun run prettier --write <file-path>
• これにより、すべてのドキュメントで一貫したフォーマットが保たれます

よくあるパターン

手順:

Run:
\`\`\`
command-to-run
\`\`\`

Then:
\`\`\`
next-command
\`\`\`

This ensures you're getting the latest changes.

次のようにしないでください: 「（X の前に Y を実行するのを忘れずに……）」と段落の中に埋め込む。

見出し:

• 「設定には環境変数を使用する」 ✅
• 「環境変数」 ❌（曖昧すぎる）
• 「設定に環境変数を使用する方法」 ❌（冗長すぎる）

リンク:

• 「SAML ドキュメントを参照してください」 ✅
• 「ドキュメントはこちらをお読みください」 ❌

注意すべきこと

• タスクを「簡単」と表現する（読者の状況はわからない）
• Metabase の機能について話すときに「私たち」を使う（「Metabase」または「それ」を使う）
• 堅苦しい言葉:「活用する」「参照する」「提供物」
• 威勢がよすぎる: 感嘆符の多用
• 説明の中に行動を埋もれさせる
• 動作しないコード例
• すぐに古くなる数値

クイックリファレンス

こう書く	こう書かない
people, companies	users
summarize	aggregate
take a look at	reference
can't, don't	cannot, do not
Filter button	`Filter` button
Check out the docs	Click here