nk-documentation-best-practices

NK ドキュメントのベストプラクティス

すべての Naykel プロジェクトで共通するドキュメントのルールです。プロジェクト固有のスキルはこのルールを拡張します。両方を適用し、競合する場合はプロジェクトのスキルを優先してください。

レビューワークフロー

• 新しい見出しには、内容が確認されるまで (review) を付けます。
• (review) が付いているセクションを更新する際は、そのセクションが完成しているか確認してください。
• 確認後は、(review) タグを削除し、プロジェクトのステータスファイルを更新します。
• ドキュメントの構成が合意されていれば、一部のセクションにまだ (review) が付いていても、ナビゲーション項目から (wip) を削除します。
• 未解決の見出しには (review) を付けたままにします。
• ドキュメントからすべての (review) タグがなくなった時点で、そのドキュメントは完成とみなします。
• ドキュメント作業を終える際は、どの見出しやドキュメントにまだ (review) タグが付いているかを明記します。

共通ルール

• 1つのドキュメントにつき、目的は1つ。 あるページでメンタルモデルの説明、すべてのプロパティの一覧、クイックスタートを扱っている場合は、分割してください。
• コードを優先。 動作が自明でない場合や、背景情報が必要な場合にのみ説明を加えます。

ドキュメントの構成

• すべてのドキュメントは、タイトルと短いリード文から始めます。
• リード文は <p class="lead">...</p> の形式で記述します。
• リード文では、そのページの内容と、読者が得られる情報を説明します。
• 具体的に書き、不要な文言は避けます。
• 独立した ## Introduction セクションは追加しません。

ナビゲーションの管理

• まだナビゲーションにないドキュメントの作業を始める際は、実際のカテゴリに追加し、開発中にアクセスできるよう名前の末尾に (wip) を付けます。
• ナビゲーションのラベルとセクションは最小限にします。ドキュメントのレビューと合意が済んだら、必要に応じて構成を追加してください。

ルールファイル

応答する前に、該当するルールファイルを読み、要約だけに頼らないでください。

コンポーネントのドキュメント → rules/component-docs.md

• 単一コンポーネントのページ
• 複数コンポーネントのページ
• バリアントとコンポーネントファミリー