インタラクティブ ドキュメント ハブ
目的
ドキュメント ハブは、セントラル メンバーシップ & SSO ハブのインタラクティブなウェブサイトです。マークダウンは依然として真実の源であり、ウェブサイトは視覚的、ナビゲーション、検索、バージョン履歴のレイヤーです。
対象読者とモード
| モード | 対象 | コンテンツの形状 |
|---|---|---|
| Simple | 一般の人、ステークホルダー、プログラマーが簡単な要約を求める人 | 簡単な言葉、カード、タイムライン、フローチャート、そして「なぜ」の説明 |
| Detail | プログラマー、QA、オペレーター | API、データベース、OAuth2、キュー、ペイロード、環境変数、テストシナリオ |
ヘッダーでモードを切り替えることができます。モードはウェブサイト全体に適用されます。モード Simple はジャーゴンを簡単な説明に置き換えますが、重要な事実を隠しません。モード Detail は完全な技術契約を表示します。
情報の構造
/docs
├── ここから始めましょう: オーバービュー、ユーザージャーニー、用語集
├── システムの動作: 登録、ライセンス、支払い、SSO
├── ビジュアルダッシュボード: システムマップ、ライセンスライフサイクル、変更履歴
├── 開発者向け: API、データベース、設計、セットアップ、テスト
└── 参照: 全てのドキュメントと変更履歴
インタラクティブな体験
| 機能 | 読者への価値 |
|---|---|
| クリック可能なシステムマップ | Next.js、NestJS、PostgreSQL、Redis/BullMQ、Midtrans、Xenditの役割を説明します。 |
| フロー シミュレーター | 登録 → 検証 → 有効化 → SSO または チェックアウト → ウェブフック → ライセンス有効化のフローを視覚化します。 |
| ライセンス ライフサイクル | 有効 → グレース ペリオド → 停止 → 再生 を状態マシンとして表示します。 |
| API エクスプローラー | フィルタリングされたエンドポイントを表示します。 Simple は使用方法を説明し、 Detail は要求/応答/認証を表示します。 |
| データベース エクスプローラー | ERD をクリックすると、テーブル、関係、列の意味が表示されます。 |
| ガイド用のツールチップ | JWT、ウェブフック、Redis、BullMQ をその文脈で説明します。 |
| グローバル検索 | ドキュメント、API、テーブル、テストシナリオを横断してトピックを検索します。 |
| 読み進めの進捗状況 | 既読のページをマークします。 |
図は SVG/React またはローカル アセットを使用して作成され、オフラインでも機能します。ランタイム中の外部の図解サービスに依存しません。
オフラインファースト PWA
- Next.js で構築されたウェブサイトは PWA としてインストールできます。
- マークダウン/MDX コンテンツ、図、検索インデックス、UI アセットはビルド時にバンドルされます。
- サービスワーカーは初回訪問後、ページとアセットをキャッシュします。
- オフラインモードでは、インジケータとコンテンツの有効な日付/バージョンが表示されます。
- フロントエンドのルート
/docsで実装を開始し、アプリケーションのデザインと一貫性を保ちます。
バージョン管理ドキュメント
ウェブサイトにはバージョン セレクターがあります。 最新、v1.0、v1.1、v1.2、など。古いバージョンは読み取ることができます。各ページには、有効なバージョン、更新日、履歴へのリンク、および 2 つのバージョンの比較オプションが表示されます。
| アーティファクト | 役割 |
|---|---|
| アクティブな docs フォルダー | 最新のコンテンツ |
versions/vX.Y/ |
ウェブサイトが表示する全てのドキュメントのスナップショット |
11-changelog/changelog.md |
人間の解釈による各リリースの概要 |
11-changelog/changelog-guidelines.md |
バージョン/変更の決定に関する規則 |
Git タグ docs-vX.Y |
スナップショットの公式ソースのマーク |
モード Simple はユーザーに影響を与える変更を説明し、モード Detail は API、データベース、オペレーションの影響を説明します。
実装の段階
- ルート
/docs、レイアウト、サイドバー、検索、テーマ、モード Simple/Detail の切り替えを作成します。 - ビジュアル オーバービュー、ユーザージャーニー、支払い、設計のページを作成します。
- マークダウン コンテンツから API、データベース、テストのエクスプローラーを作成します。
- オフライン PWA、バージョン セレクター、変更履歴、およびバージョンの比較を追加します。
完了の定義
- 一般の人々は、ジャーゴンを使用せずに、ハブの目的と主なフローを理解します。
- プログラマーは、同じポータルから API、データベース、設計、テストの詳細にアクセスできます。
- メイン ページ/図がキャッシュ オフラインで開くことができます。
- 読者はドキュメントのバージョンを選択し、変更履歴を読むことができます。
- ビジュアル コンテンツは、元のマークダウン ソースに戻ることができます。