ナレッジ管理ガイド

Index

1.はじめに
1.1.本ドキュメントの紹介
1.2.本ツールの紹介
2.利用方法
2.1.マイグレーションナレッジの準備
2.1.1.新規に作成する場合
2.1.2.既存ファイルを更新する場合
2.2.アイテムの作成・編集
2.3.編集内容の確認・保存
3.FAQ
3.1.ナレッジ作成時の注意事項
3.1.1.複数行にまたがる検索が実行できない
3.1.2.クラス名の前方一致防止
3.1.3.同名メソッドの検出防止

1.はじめに


1.1.本ドキュメントの紹介


本ガイドは、ナレッジ管理ツールの使用方法について説明したドキュメントです。



1.2.本ツールの紹介


本ツールは、マイグレーションナレッジをGUI 上で容易に作成、管理することができるツールです。 マイグレーションナレッジは、マイグレーションに関するノウハウとして、移植箇所を抽出するための検索条件、移植難易度、移植工数 (移植概算ライン) 等が設定可能です。

本ツールでは大きく以下の情報を扱うことが可能です。

Table 1. 本ツールで扱う情報

項目 説明
マイグレ―ションに関するノウハウガイド（HTML） マイグレーションに関するノウハウをドキュメント形式（HTML）で作成、保存できます。 保存したHTMLファイルをナレッジベース検索ツールから参照することにより、検索実行結果から直接リンク参照することができます。
修正箇所の検索情報（XML） 修正箇所の検索情報をナレッジアイテムとしてXML 形式で作成、保存できます。 保存したXMLファイルをナレッジベース検索ツールの入力情報とすることにより、検索ロジックとして利用することができます。


Figure 1. ナレッジ管理ツール

ナレッジ管理ツール




2.利用方法


2.1.マイグレーションナレッジの準備


編集対象のマイグレーションナレッジを準備します。

新規にマイグレーションナレッジファイルを作成する場合と、既存のマイグレーションナレッジファイルを編集する場合の手順について以下で説明します。

[Note] Note

以降の処理は「ナレッジ管理ツール」パースペクティブを表示して実行してください。

Window→ Open Perspective→ Other→ ナレッジ管理ツール



2.1.1.新規に作成する場合


マイグレーションナレッジを新規に作成する手順は以下です。

  1. Eclipse 上で適当なプロジェクトを生成します。

    File→ New→ Project

  2. プロジェクトを選択して、「New」ウィザードを表示します。

    Project右クリック→ New→ Other

  3. Newウィザードで「ナレッジXMLファイル」を選択します。

    Other→ ナレッジXMLファイル

  4. ナレッジXMLファイルウィザードが表示されるので、ガイドのサブジェクトや出力先を指定してください。

    本例ではマイグレーションナレッジファイルをプロジェクト直下に作成しています。

  5. Finish をクリックするとプロジェクト直下にマイグレーションナレッジファイル（XML）が生成されます。



2.1.2.既存ファイルを更新する場合


既存のマイグレーションナレッジファイルを更新する場合も適当なEclipse プロジェクト内にファイルを置いてください。

[Note] Note

GitHub 上に公開されている migration-knowledge リポジトリ をインポートすることで現在公開中のナレッジを編集することが可能です。

Gitプロジェクトのインポート方法については、Gitドキュメントを参照ください。


2.2.アイテムの作成・編集


ナレッジに関するアイテムの作成・編集手順は以下です。

  1. マイグレーションナレッジファイルのオープン

    準備したマイグレーションナレッジファイルを開きます。

    XMLファイル右クリック→ Open With→ ナレッジエディタ

  2. ナレッジエントリービューの操作

    個々のアイテムはナレッジエントリービュー上で追加・参照・更新・削除します。 作成したアイテムはドキュメント作成等に活用できます。

    Figure 1. ナレッジエントリービュー

    ナレッジエントリービュー

  3. ナレッジに関するアイテムの作成

    アイテムの作成は以下の手順で実施します。最初はアイテムが1つもないため、必ずカテゴリを作成することになります。

    • カテゴリ作成

      ナレッジエントリビュー上で未選択の状態で右クリック→ カテゴリ登録

    • ナレッジ作成

      カテゴリ右クリック→ ナレッジ登録

    アイテムは、以下の種類があります。

    Table 1. アイテムの種類

    項目 説明
    カテゴリ ドキュメント構成の章・節のタイトルに相当するアイテムです。タイトル情報のみ保持します。
    ナレッジ ドキュメント構成の章・節に記述されるナレッジコンテンツに相当するアイテムです。 DocBook#Artile形式のコンテンツ情報のみ保持します。
    チェックアイテム 該当ナレッジの移植判断情報を保持するアイテムです。検索手順、移植要因、難易度などの情報を保持します。
    検索情報 ナレッジベース検索ツールが検索の際に使用する検索ロジックとなるアイテムです。


    Figure 2. ナレッジエントリビューで表示されるアイテム

    ナレッジエントリビューで表示されるアイテム


  4. ナレッジ管理エディタの操作

    登録されたアイテムの編集やドキュメント構成の作成を行います。 ナレッジ管理エディタには以下の種類のタブがあります。

    Table 2. タブの種類

    項目 説明
    ドキュメンテーション 作成するHTML ドキュメントの章構成を編集することができます。 見出しを作成後、ナレッジエントリービューからカテゴリをドラッグ&ドロップすることでドキュメントを構成していきます。
    ナレッジ詳細 ナレッジのコンテンツをDocBook#Article 形式で編集するエディタです。 エディタ上で右クリックを行い、タグのテンプレートを挿入することもできます。
    [Important] Important

    独自にセクションが作成され章構成が崩れるのを防ぐため、 <section>タグは使用できません。

    チェックアイテム ナレッジエントリービューで選択しているチェックアイテム情報および検索情報を編集することができます。


    Figure 3. ドキュメンテーションタブ

    ドキュメンテーションタブ


    Figure 4. ナレッジ詳細タブ

    ナレッジ詳細タブ


    Figure 5. チェックアイテムタブ

    チェックアイテムタブ


    以下にチェックアイテムタブで編集するチェックアイテム情報および検索情報の各入力項目の説明をします。

    Table 3. チェックアイテム情報

    項目 説明
    検索手順 登録するナレッジとしてどのような移植箇所をどのように検索するのかの概要を文章で入力します。
    検索実施 ナレッジベース検索ツールで検索する際に、実際に検索対象とする場合はチェックを有効にします。
    移植要因 移植が必要となる理由として該当する項目を選択します。
    難易度 移植作業の難易度を選択します。
    [Note] Note

    選択基準は以下となります。

    • 高

      実装内容の大規模な修正が必要で、実装や設定等の大幅な見直しが必要

    • 中

      実装内容を考慮した小規模な修正が必要

    • 低

      実装内容を考慮せず軽微な修正で対応可能

    • 不明

      難易度不明

    • 移植不可

      移植不可
    難易度詳細 移植作業の詳細な難易度を選択します。
    [Note] Note

    選択基準は以下となります。

    • 高

      難易度が 高であるもの

    • 中

      難易度が 中であるもの

    • 低1

      難易度が 低であり、置換レベルで対応不可能であるもの

    • 低2

      難易度が 低であり、置換レベルで対応可能であるもの

    • 不明1

      難易度が 不明であり、移行先環境にて該当機能がなく難易度を判断できないもの

    • 不明2

      難易度が 不明であり、移行先環境に該当機能があるかどうかも不明で難易度を判断できないもの

    • 移植不可

      難易度が 移植不可であるもの

    目視確認 設定したロジカルな検索条件だけでは移植項目が特定できない場合の目視による調査方法または、判定基準等を入力します。
    ヒアリング確認 開発元に確認しなければ移植の必要性が判断できない項目の場合の開発元への確認内容を入力します。


    Figure 6. チェックアイテム情報

    チェックアイテム情報


    Table 4. 検索情報

    項目 説明
    検索対象ファイル 検索対象とするファイル名を入力します。正規表現での入力が可能です。
    検索キーワード 1 検索モジュールに渡すパラメータを入力します。正規表現や XPath での入力も可能です。
    [Note] Note

    入力するパラメータについては、検索モジュールによって変わります。検索モジュール概要を参考にパラメータを入力してください。

    検索キーワード 2 検索モジュールに渡すパラメータを入力します。正規表現や XPath での入力も可能です。
    [Note] Note

    入力するパラメータについては、検索モジュールによって変わります。検索モジュール概要を参考にパラメータを入力してください。

    検索モジュール 検索モジュール概要を参考に検索したいモジュールを選択します。
    [Note] Note

    未選択の場合は、標準検索機能により検索が実行されます。標準検索機能は、検索対象ファイルでヒットしたファイルに対して検索キーワード 1で検索後、検索キーワード 2でさらに検索を行います。

    検索モジュール概要 検索モジュールの概要説明が表示されます。
    ライン数算出 検索にヒットした場合にライン数に入力した値を移植工数として加算する場合はチェックを有効にします。
    非算出理由 ライン数算出を無効にする場合は、その理由を入力します。
    不明 / TODO ライン数が不確定な場合に、該当する項目を選択します。
    ライン数 移植に要するおおよその修正ライン数を入力します。
    ライン数根拠 入力したライン数の根拠を入力します。
    調査内容 修正ライン数を算出するための調査方法等を入力します。


    Figure 7. 検索情報

    検索情報




2.3.編集内容の確認・保存


編集したマイグレーションナレッジファイルを確認、保存します。



3.FAQ


3.1.ナレッジ作成時の注意事項


ここでは実際にナレッジを作成する際に注意すべき事や工夫すべき事について記述します。



3.1.1.複数行にまたがる検索が実行できない


現行のTUBAMEでは複数行にまたがる検索が行えません。

Figure 1. 複数行検索例 


getServlet().log
(resources.getMessage(locale, "users.error.invoke",
operation), e);


正規表現としては「log[\s]*\(」とすることで上記のlogメソッドを検索することが出来ますが、 現行のTUBAMEでは複数行にまたがる検索が行えないため、このような正規表現を用いて検索することは出来ません。

Eclipseのフォーマット機能を利用することで「log」の後ろに「(」が来るようにすることもできますが、 「log」の後ろにコメントが入っている場合はフォーマット処理は行われません。 したがって、事前にCheckstyleなどの静的解析ツールを利用して、このようなコードが無いかチェックをし、 そのうえでフォーマット機能を利用するようにした方が良いと考えられます。



3.1.2.クラス名の前方一致防止


検索条件として、検索キーワード１にFQCN、検索キーワード２にメソッドや定数を指定した場合に、 前方一致してしまう別クラスを検出してしまう問題があります。

例えば、javax.servlet.http.HttpSessionクラスのgetValue()メソッドを検索する場合、 検索キーワード１に「javax\.servlet\.http\.HttpSession」、 検索キーワード２に「getValue\(」を設定していると、 javax.servlet.http.HttpSessionBindingEventクラスのgetValue()メソッドを利用してい る場合に検出されてしまうと問題があります。本問題については、「HttpSession」の後ろに英数字が入らないような形での キーワード指定「javax\.servlet\.http\.HttpSession[^0-9a-zA-Z]」と指定するなどが考えられます。



3.1.3.同名メソッドの検出防止


検索条件として検索キーワード１にFQCN、検索キーワード２にメソッドや定数を指定した場合に、 検索対象ではないクラスの同名メソッドを検出してしまう問題があります。

例えば、javax.servlet.ServletContextクラスのlog(Exception, String)メソッドを検索す る場合、 検索キーワード１に「javax\.servlet\.ServletContext」、検索キーワード２に「log\(」を設定していると、クラス内で定義された同名のメソッドが検出されたり、log(Exception, String)メソッドではなく、 log(String, Throwable)メソッドが検出されてしまう問題があります。 なお、本問題については現在キーワードでの防止策は確認できていないため、目視によるチェックで対応する必要があります。