概要画像では、OpenDocs は以下を行う場所として紹介されています：図を作成し、共同で文書化し、知識を整理し、結果を共有または公開することこれを利用する有用な方法は、各文書を単発のファイルではなく、維持管理されるナレッジベースの一部として扱うことです。
OpenDocs は、書面コンテンツと視覚モデルを統合するウェブベースの知識管理およびドキュメント環境として説明されています。Visual Paradigm のパイプライン機能を使用すれば、Visual Paradigm Desktop または Online で作成した図を OpenDocs に接続でき、手動でエクスポートされた静的画像への依存を減らすことができます。利用可能な機能は、Visual Paradigm のエディションと設定によって異なる場合があります。
1. ナレッジベースを計画する
ページを作成する前に、そのスペースの目的と利用者を明確にしてください。焦点を絞った構造にすることで、情報が探しやすく、維持管理しやすくなります。
例えば、製品またはシステムのナレッジベースは以下のように構成されることがあります：
-
概要— 目的、範囲、所有者、および主要ページへのリンク
-
アーキテクチャ— システムの文脈、コンポーネント、統合、およびデプロイ
-
プロセス— ワークフロー、手順、および意思決定ポイント
-
データ— エンティティ、データフロー、および定義
-
運用— 運用マニュアル、監視、復旧、およびサポート連絡先
-
意思決定— 設計上の選択、その根拠、および結果
-
用語集— 共通用語と略語
トップレベルはコンパクトに保ち、詳細な内容は焦点を絞ったサブページに配置し、関連するページ同士を相互にリンクしてください。
2. 明確な概要ページを作成する
新規読者が方向性を把握できるよう支援するページから始めます。以下を含めてください：
-
目的：このナレッジベースがカバーする範囲。
-
対象者：誰がこれを利用すべきか。
-
範囲：何が含まれ、かつ有用であれば何が含まれないか。
-
所有権：誰がコンテンツを維持するか。
-
ナビゲーション：最も重要なセクションへのリンク。
-
鮮度：レビュー日付、または古くなったコンテンツを報告するためのガイドライン。
プロジェクトをすでに知らない読者向けに執筆してください。一般的な略語は略さずに書き、重要な図の背景にある文脈を説明してください。
3. コンテンツの草案作成と構造化
OpenDocs は、同じワークスペースでドキュメント作成とビジュアルコンテンツの両方をサポートしています。検索結果は、Markdown 指向のエディタと、一部のワークフローでは WYSIWYG 編集体験を説明しています。アカウントで利用可能な編集モードを使用してください。
信頼できるページのパターンは以下の通りです：
-
要約：数文で要点を述べる。
-
文脈：なぜこのトピックが重要なのか、そしてどのような前提が適用されるか。
-
ビジュアル：構造、動作、または関係性を説明する図。
-
詳細：定義、手順、ルール、または補足説明。
-
関連ページ：前提条件と続編資料へのリンク。
-
所有者とレビュー日：誰がページを確認し、いつ確認するか。
手順については、説明的な見出し、短い段落、リストを優先してください。読者が項目を比較したり構造化された事実をスキャンしたりする必要がある場合は表を使用してください。テキストで説明されていない情報を図に任せないようにしてください。
4. 質問に答える図を選択する
読者に理解させたい問題に基づいて視覚モデルを選択してください：
-
フローチャートまたは BPMN：何が起き、どのような順序で起きるか？
-
UML ユースケース図またはアクティビティ図：誰がシステムと相互作用し、どのような動作が発生するか？
-
UML コンポーネント図またはデプロイメント図：構成要素は何であり、どのように配置されているか？
-
シーケンス図：参加者は時間経過とともにどのように通信するか？
-
ERD：どのようなデータエンティティが存在し、それらはどのように関連しているか？
-
マインドマップまたはコンセプトマップ：アイデアはどのようにグループ化され、どのように接続されているか？
-
ガントチャート、ロードマップ、または作業分解構造（WBS）：どのような作業が計画されており、それらはどのように組み合わさっているか？
Visual Paradigm の資料は、UML、BPMN、ERD、マインドマップ、プロジェクト計画の可視化など、図のタイプを含む OpenDocs のワークフローを説明しています。特定の図のタイプを基にプロセスを構築する前に、そのタイプがお客様のエディションで利用可能であることを確認してください。
各図にタイトルと短い説明を付けてください。略語を定義し、重要な境界にラベルを付け、聴衆に適した詳細レベルを維持してください。図が読みづらくなった場合は、高レベルのビューと 1 つ以上の詳細ビューに分割してください。
5. 図をドキュメントに追加する
概要画像は、単純な作成サイクルを示唆しています：視覚化を作成し、テキストを補完する場所に配置し、その読み方を説明します。
実践的な手順は以下の通りです：
-
まず周囲の説明を書き、図に明確な目的を持たせてください。
-
利用可能なエディタまたはモデリングツールで図を作成してください。
-
アカウントで利用可能な統合機能を使用して、関連ページに挿入または埋め込んでください。
-
範囲と主要なポイントを説明するキャプションまたは近くのテキストを追加してください。
-
読者が使用するページ幅でラベルが読み取れるか確認してください。
-
編集ビューだけでなく、読者としてページを確認してください。
図が Visual Paradigm のパイプラインを通じて送信されると、ソースはモデルアーティファクトを OpenDocs で利用可能にし、ドキュメントで使用するために選択するワークフローを説明します。これにより、古くなったコピーを減らすことができますが、チームは埋め込まれたアーティファクトが意図したモデルとリビジョンを指していることを確認する必要があります。
6. 軽量なレビュープロセスで協力する
一貫したプロセスを使用して、協力が矛盾する編集を生むのではなく、正確性を高めるようにしてください：
-
責任を割り当てる：各重要なページまたはセクションの所有者を指名してください。
-
ドラフト作成：コンテンツを作成し、それを説明するために必要な視覚要素を含めてください。
-
レビュー：専門家に正確性をチェックしてもらい、チーム外の読者に明確さをチェックしてもらってください。
-
変更の解決：文章と図の両方に対する編集について合意する。
-
公開または共有：レビュー済みのバージョンを意図した対象者に利用可能にする。
-
再確認：システムまたはプロセスが変更された際にページを見直す。
この画像はチームコラボレーションを示していますが、具体的なコラボレーション制御機能や利用可能性は異なる場合があります。すべてのアカウントが同じ共有または編集オプションをサポートしていると仮定するのではなく、OpenDocs ワークスペースに表示されている制御機能を確認してください。
7. ナレッジベースの整理と維持
優れたナレッジベースには継続的な手入れが必要です。ページはスキャンしやすい大きさに保ち、一貫したタイトルを使用し、同じ説明を複数の場所に重複させるのではなく、関連するトピックをリンクしてください。
各重要なページについて、以下を追跡してください：
-
明確な所有者
-
意図した対象者
-
リンクされたモデルまたはデータの真実の源
-
最終レビュー日
-
既知の制限事項または未解決の質問
図が変更された場合、その周辺のテキストも再確認してください。図は最新であっても、説明、用語、またはリンクされた手順が最新ではない場合があります。
8. 慎重に共有または公開する
ページまたはスペースを共有する前に、以下を確認してください：
-
意図した対象者がアクセスできるかどうか
-
コンテンツに機密情報または社内限定情報が含まれているかどうか
-
共有ビューで図とレイアウトが期待通り表示されるかどうか
-
受信者が単一のページを必要としているのか、それともナレッジベース全体を必要としているかどうか
-
資料が外部の読者向けに準備ができているかどうか
具体的な共有および公開オプションは、アカウントと設定に依存します。概要画像の「共有」ステージは、特定の公開先や権限モデルを保証するものではなく、ワークフローの目標として扱ってください。
9. 再利用可能なページチェックリスト
ページを準備完了とみなす前に、以下を確認してください：
-
明確なタイトルと目的を持っている
-
意図した対象者にとって意味が通じる
-
見慣れない用語を定義している
-
特定の質問に答える図を使用している
-
テキスト内で重要な図表を説明する
-
関連ページやソース資料へのリンクを設ける
-
所有者とレビュー日付を明記する
-
共有ビューまたは閲覧者向けビューで確認済みである
ワークフローの例
新しいサービスの文書化には、まずその目的と所有権を説明する概要ページから始めます。ユーザーと外部依存関係を示すシステムコンテキスト図を追加し、主要な構成要素を示すコンポーネント図を作成します。その後、主要なリクエストフローと運用手順を別々のページに文書化します。概要ページからこれらのページへのリンクを設け、サービスチームとレビューを行い、対象読者に対して適切なビューを共有します。基盤となるモデルが変更された場合は、関連する図表とその説明を更新または再確認してください。
中核となる原則は単純です：記述、図表、構成、共有プロセスを常に連携させることこれこそが、ページや図表の集まりを実用的で保守可能なドキュメントへと変える要素です。