Excel のプログラム設計書、仕様書をWeb化する際に、どんなことを検討すべきかまとめてみました。
まとめた結果を記載します。

設計ドキュメントをWeb化したい欲求を持つに至る原因

Web化したい欲求を持つに至る原因について記載します。
個人的な経験で他にも理由はあるかと思います。

  • Excelだと差分がわからない
    Excelだと、以前のVersionとの差分がわからないため、変更箇所の色を変える場合があります。
    Excel間のDiffを取る方法もありますが、Excel以外のツールが必要になります。
    Excelファイル同士をdiffするための方法 - Qiita

  • Googleスプレッドシート、ドキュメントだと組織外への共有ができない場合がある
    個人的に、ブラウザで編集ができ、共有もできるGoogleスプレッドシート、ドキュメントでの設計書作成は快適に思いますが、組織内のみへの共有を許している場合、組織外部への共有はできません。
    外部への共有は、結局 Excel化が必要で、そうなると外部のユーザーは編集が難しい可能性があります。

  • 案. 組織内と組織外が作成するドキュメントを明確に分ける
    Google スプレッドシート、ドキュメントのデメリットを記載していて、組織内と組織外で作成するドキュメントを明確に分けてしまうという案が浮かびました。
    基本設計は、組織内で、詳細設計以降を組織外へ依頼するケースなどこの方法でいいかもしれません。
    Google スプレッドシート、ドキュメントにすることで、Google Cloud Search の恩恵を受けることができます。

  • その場限りのドキュメント問題
    0-1フェーズ後の、1-100フェーズに入ると、システム変更要点のみをまとめたいケースがあります。
    その際のドキュメントは、システム変更要点をまとめているが、システム変更時のみ使われ、その後利用されることがないドキュメントになります。
    検索が容易な仕組みが存在する場合は、変更後も利用されるかもしれませんが、Excel設計書の場合、個人的に検索性が悪く、使用されるケースが個人的な経験上はありません。
    またこのケース、0-1フェーズで作成された設計書がメンテナンスされないと、ドキュメントの信頼性が失われ、ドキュメントを参照する人が少なくなります。

設計ドキュメントのWeb化にあったほうがいい機能

設計ドキュメントのWeb化にあったほうがいい機能について以下に記載します。
他にもあるかもしれません。

  • GA によるWeb解析
  • 読まれないドキュメントを見つける
    • 読まれないドキュメント
      • 価値がない。捨てる。
      • 価値があるが知られていない。
        • 宣伝する

  • 読まれるドキュメントを見つける

    • 宣伝する

  • コンテンツレコメンド

  • 似ている設計書を探す。 アイテムレコメンド。

    • Wikiだと良い感じにできるが、設計ドキュメントで良い感じになるかは実際にやってみないとわからない。

  • 協調フィルタリング

    • この設計書を見た人は、この設計書も見ています を実装する。
    • GAでのデータを元に協調フィルタリング は実現できる。この際、コンテンツレコメンドで上がってくる設計書は除外する。

  • ツリーと カテゴリ、タグ
    ツリー、カテゴリ、タグもあった方が良い機能かと思います。

  • ツリー

    • ツリーは機能単位。

  • カテゴリ

    • ドキュメント種類に対するカテゴリ、例えば 画面遷移図 等

  • キーワード

    • これは用語辞書に登録するようなキーワード。業務用語。
    • 文書の形態素解析で取り出すのも良さそう。

  • 全文検索

  • 静的サイトジェネレータだと、見出し、タイトルの検索までが多い。
  • Wiki のようなツールだと全文検索ができるが、版管理が難しそう。

  • 静的サイトジェネレータ と何かの全文検索の組み合わせが良い気がする。

  • 文書校正ツール

  • ツール候補

    • TextLint
    • Redpen

  • 構成管理にチェックインされたマークダウンをCIで校正ツールでチェックする。

  • 版管理

  • 版管理ができること

  • 静的サイトジェネレーターだとマークダウンがテキストで版管理される。

  • ドキュメント監査
    これは機能ではなく考慮。
    内部監査などがある場合、監査に必要な観点がWebのドキュメントで担保されている必要がある。

  • UML等のダイアグラムがかける

  • 案1 画像を使う
    • 画像生成元ネタが、テキスト形式のファイルであれば構成管理上に載せておけば見れる。
  • 案2 作図ツールを使う

既存ドキュメントの移行

既存ドキュメントの移行作業も発生するかと思います。
ドキュメントサイト作成時に移行する、移行しない（その都度移行） 2パターンがあるかと思います。

実はExcelドキュメントでも問題がないパターン

よくよく考えるとExcel管理で問題ないケースのあるのではと思い、記載します。

  • 開発規模が大きくない。
    システム改修の開発規模が小さく、原本直接編集でも何とかなるレベルの規模感。
    そもそも全体のドキュメント数が少ない、人間が十分仕様把握できる規模。

  • 並行開発で競合するドキュメントがそこまで多くない。
    並行開発が行われているが、開発ラインで設計書類の重複が少ない。
    本線修正でも競合リスクが少ない。

  • 構成管理からドキュメントを取り出すという行為が面倒なだけで、Excelで事が足りている

  • 構成管理にファイルを配置するタイミングを変更する。
  • 構成管理から取り出しやすくするツールを作る。

今のところ動的にHTMLを生成するツールではなく、静的サイトジェネレータを使う方向で考えていて、いくつか静的サイトジェネレータを試して、必要な機能が網羅されてそうなものを使おうかと思っております。
以上です。

コメント

カテゴリー

最近の投稿