BoKマニュアル

Cozy BoK source and site operation manual.

Dashboard

このManualは、BoK標準運用の手順と責務分担をまとめる技術マニュアルです。プロジェクト固有のルールはリポジトリのドキュメントに記録します。

Quick Links

Basic Operations

  • cozy bok create --save <dir>: BoK source scaffoldを作成します。
  • cozy bok create-category <name> --project <dir>: カテゴリDashboard、記事seed、用語seedを追加します。
  • cozy bok doctor <dir>: BoK source treeを検査します。
  • cozy bok build <dir> --strategy preview: SmartDox/Antoraを使って website.d を生成します。
  • cozy bok preview <dir> --port <port>: 生成済み website.d をローカルWebサーバーで確認します。
  • cozy bok publish <dir> --dry-run: 公開前の計画と副作用境界を確認します。

Source Document Formats

BoKのsource文書形式はGitHub MarkdownとSmartDoxです。一般のKnowledge ContributorにはGitHub Markdownを推奨します。記事本文を通常のMarkdownとして書けるため、GitHub上の編集、レビュー、Pull Requestとの相性が良いからです。

BoKのフル機能を使いたい上級者にはSmartDoxを推奨します。SmartDoxはBoK metadata、用語連携、RDF連携、SmartDox固有の構造化表現を扱えます。

マルチリンガルBoKはSmartDoxのみを対象にします。GitHub Markdownは単一言語の通常記事向けとして扱います。

Glossary Term Classification

用語分類は、未分類の候補を確認し、モノ/コトの補助線で整理した上で、BoK内での役割に基づいて用語タイプを決める作業です。

  1. 未分類の用語を確認します。
  2. 記事、シナリオ、参考資料、Project/CML情報から、その語がBoK内で何を担うかを確認します。
  3. 存在として扱う対象は、concept、entity、actor、role、resource、artifactから選びます。
  4. 起きる、行う、変化する、制御する対象は、event、action、process、task、rule、state、scenarioから選びます。
  5. 判定に迷う場合は未分類のまま残し、根拠記事や関連用語を先に整備します。
  6. 分類後は用語ハブで定義、関連記事、RDF接続、Project/CML接続を確認します。

Actor Operations

BoK運用では、Knowledge Contributor、BoK管理者、サイト管理者の責務を分けます。Knowledge Contributorは、ある知識のKnowledge OwnerとしてGit sourceを編集します。自分がownerではない知識への修正はPull Requestで提案します。BoK管理者とサイト管理者はPull Requestを境界にレビュー、merge、公開判断を行います。

知識提供者 / Knowledge Contributor

  1. 自分がKnowledge Ownerである記事、用語、カテゴリ、media、publicationなどのGit sourceを編集します。
  2. ownerではない知識への修正は、作業branchで差分を作りPull Requestとして提案します。
  3. cozy bok doctor で構造、メタデータ、リンク、用語、RDFの基本品質を確認します。
  4. cozy bok build --strategy preview と cozy bok preview でDashboard、Category Pages、Glossary、Term Hub、RDF Graph、Recent Changesを確認します。
  5. Git commitし、作業branchをpushします。
  6. 必要に応じてPull Requestを作成し、該当Knowledge OwnerまたはBoK管理者へレビューを依頼します。

BoK管理者 / BoK Manager

  1. Pull Requestを受け取り、内容、構造、用語、RDF、整合性をレビューします。
  2. 必要に応じてPull Request上で修正依頼し、承認後にmainへmergeします。
  3. cozy bok publish --dry-run で公開前のビルド、配備、検証計画を確認します。
  4. 高品質で一貫性のある知識だけを公開フローへ渡します。

サイト管理者 / Site Administrator

  1. ホスティング環境、upload設定、secret、アクセス制御を管理します。
  2. 公開対象の変更はPull Requestで確認できる状態を前提に、stage/upload workflowを運用します。
  3. 監視、バックアップ、障害対応、キャッシュ削除などのサイト運用を担当します。

Source / Generated Boundary

Knowledge Contributorが編集するのはGit sourceだけです。Knowledge Ownerである知識は直接保守し、ownerではない知識はPull Requestで提案します。

編集するSource

  • src/main/doxsite/**/*.dox
  • src/main/doxsite/**/*.md
  • src/main/doxsite/**/category.yaml
  • src/main/doxsite/glossary/**/*.dox
  • src/main/media/** for durable article-media inputs
  • src/main/publication/** for the durable publication registry
  • src/main/extensions/rdf/** only for explicit admitted non-derived declarations

生成物は編集しない

  • website.d/
  • doxsite.d/
  • antora.d/
  • target/
  • repository/

The standard Manual, History dashboard, RDF, machine metadata, and UI are generated outputs; they are never edited as source.

Page Types

  • Home: BoK全体Dashboard。
  • Category Dashboard: カテゴリ単位のKPI、記事、用語、運用メモ。
  • Glossary: BoK全体の語彙Dashboard。
  • History: BoK運用と公開履歴Dashboard。
  • Manual: BoK運用手順の入口。

Operation Notes

BoKの標準ページはDashboardとして扱い、通常記事とは異なる情報集約ページにします。Glossary、History、Manualはカテゴリ一覧ではなくBoK Consoleとして扱います。Manualは運用手順ページなので、SmartDoxの自動用語リンク対象外です。