デザインシステムの説明書を作り、古くならないように保つ

## 原則から部品まで、説明書に書く範囲を決める 文書化の対象には、原則、意思決定、仕事の進め方というシステムの無形の基盤と、パターン、コンポーネント、利用規則、実装ツールという有形の資産の両方を含める。執筆を始める前に対象範囲を明示し、抜けが後から判明する不意の問題ではなく、計画的に扱えるバックログ項目になるようにする。 ## 説明書をページに分け、困り事の多い所から書く 作業を、それぞれ単独で完結するページに分割する。最も摩擦を生んでいる領域を優先し、次に使用頻度が高い、または依存関係の多いコンポーネントを扱う。進捗を追跡し、制約の変化に応じて優先順位を見直す。チームが確実に保守、検索、共有できるツールであれば、種類を問わず使ってよい。 ## 部品ごとに、4つの問いに答える形で説明を書く 各コンポーネントについて、次の4つの問いに明確に答える。状態と選択肢を含め、それは何か。類似する代替案ではなく、なぜそれを選ぶのか。どのような文脈なら適切なのか。対応するバリエーション、例、明示的な推奨事項と禁止事項を含め、どのように使うべきか。 ## まずデザイナーと開発者に向けて書き、ほかの担当者向けは短くする まずデザイナーと開発者に、明確な動作、判断基準、実装上の参照情報、コードやストーリーへのリンクを提供する。プロダクト、QA、リサーチの担当者には、より短い確認経路を用意する。他のシステムの優れたパターンを再利用する場合も、そのまま写さず用途に合わせて調整する。見た目の完成度より、必要な情報へ機能的にアクセスできることを重視する。 ## 出す前に、説明書とデザインとコードが合っているかを確かめる 文書を生きたプロダクトとして扱う。批評の場で新しいコンポーネントと指針をレビューし、プロジェクト開始時に文書化の必要性を評価し、利用者による試験とアクセシビリティ確認でコンポーネントを検証する。リリース前にデザイン、コード、文書の整合を確認する。保守の習慣が機能していないことを証拠が示した場合は、その習慣を変える。