Sphinx + blockdiag による非プログラマのための使える図解の紹介

はじめに

こんにちは。Sphinx Advent Calendar 2012 の4日目のエントリです。@tk0miyaより受け取りました。

Sphinx を使い始めてまだ日が浅いですが実際に仕事で使ってみてすばらしいツールだと今更ながら気づき、Sphinx に特化したエントリというよりも Sphinx + blogckdiag を使って仕事に使えるダイアグラムの表現方法についてご紹介します。

非プログラマでも簡単に作成ができ修正も簡単、イライラしないでサクサクと図が書けます。

ソフトウェア開発プロジェクトで作成されるドキュメント(特にマニュアルで利用)は顧客に説明するための図解を多用します。これまでの経験で

  • Word/Excel の描画ツールをつかってがんばって作った図
    調整と編集がとても大変
  • Visio を使ってわかりやすく綺麗に作成されているが、Word/Excel/PowerPoint に貼り付け、画像のため編集が手間
  • 最近増えたと思われる開発環境としての Mac 利用者で使える描画ツールがほしい
    • Mac では OmniGraffle というすばらしいツールがありますが全員分のライセンスは難しい

このような状態でした。Visio や Omnigraffle は愛用しておりすばらしいツールですがもっとお手軽な描画ツールが欲しいとさがした結果、Sphinx + blockdiag という組み合わせが実用的なことに今更ながら気づきました。

基本的な Sphinx / blogckdiag の使い方ではなく、仕事で使える図解例のコードを紹介したいと思います。

図解のためのフォーマット

Sphinx + blockdiagでどのようなことができるでしょうか。
仕事で使えると思うパターンを以下の図をコードとともに紹介します。

  1. 手順…順番に説明するとき、ステップや時系列説明
  2. リスト…グループ毎に分かれた場合の説明
  3. リング/循環…連続したプロセスの説明
  4. 階層…重み付けされたモノの説明
  5. 集合の関連…グループの関連、アイデア、マインドマップ
  6. マトリクス…関連度合いの説明など

1. 手順

ステップや時系列説明に利用するダイアグラムです。

.. blockdiag::

   blockdiag {
     A [label = "ネタを探す"];
     B [label = "記事を書く"];
     C [label = "推敲する"];

     A -> B -> C;

   }

2. リスト

ダイアグラムと対応した説明をつけています。 :desctable: を利用すると説明表を自動生成してくれます。

.. blockdiag::
   :desctable:

   blockdiag {
     A [numbered = 1, label = "オペレーティングシステム", description = "CentOS 6.3"];
     B [numbered = 2, label = "ミドルウェア", description = "Apache 2.4 / Python 2.7.2 / Django 1.4.2"];
     C [numbered = 3, label = "データベース", description = "PostgreSQL 9.2.1"];

     A -- B -- C;

     // 配置
     node_width = 220;
     span_width = 20;
     span_height = 20;
    }

3. リング/循環

連続したプロセスなどの説明に利用するダイアグラムです。

.. blockdiag::

  blockdiag {
    default_shape = roundedbox
    node_width = 160;

    A [label = "タスク準備"];
    B [label = "プランニングミーティング"];
    C [label = "タスク割当"];
    D [label = "デモンストレーション"];
    E [label = "中間ミーティング"];
    F [label = "デイリースクラム"];

    A -> B -> C;
    D <- E <- F;
    C -> F [folded];
    D -> A [folded];
  }

4. 階層

プロジェクトチーム、組織など重み付けがある情報の説明に利用するダイアグラムです。

.. blockdiag::

   blockdiag {
    //縦書きモード
    orientation = portrait

    A [label = "プロジェクトチーム"];
    B [label = "開発チーム"];
    C [label = "斉藤"];
    D [label = "高山"];
    G [label = "品質チーム"];
    H [label = "佐藤"];
    I [label = "田辺"];

    A -> B -> C;
         B -> D;
         A -> G;
         G -> H;
         G -> I;
  }

5. 集合の関連

グループの関連、グループのメンバーなど集合に関するダイアグラムです。

.. blockdiag::

   blockdiag {
     A [label = "スクラムチーム"];
     B [label = "クロダ"];
     C [label = "サカモト"];
     D [label = "タニグチ"];
     E [label = "コンドウ"];
     F [label = "サトウ"];
     G [label = "ナカジマ"];
     H [label = "ソウマ"];
     I [label = "キタダ"];
     J [label = "コジマ"];

     A -- B -- C -- D;
     A -- E -- F -- G;
     A -- H -- I -- J;

     group first_group {
        label = "設計チーム"
        B; C; D;
     }

     group second_group {
        label = "開発チーム";
        color = "#77FF77";
        E; F; G;

     }

     group {
         label = "試験チーム";
         color = "#FF0000";
         H; I; J;
     }
  }

6. マトリクス

ここまで来ると無理矢理感がすごいですが、マトリクスっぽいダイアグラムです。

.. blockdiag::

    blockdiag {
      A -- B [style = none];
      C -- D [style = none];
      B -- D [style = none, folded];
      C -- A [style = none, folded];

      // ブロックのサイズと余白指定
      node_width = 200;
      node_height = 100;
      span_width = 5;
      span_height = 5;

    }

さいごに

いくつか blockdiag でやる必要の無い図がありますが、例ということでご了承ください。

Sphinx + blockdiag でこのような表現が簡単にできます。ブロック図生成ツール blockdiagの属性の説明にはさらに細かい設定が可能で作成したいダイアグラムに合わせた調整ができます。

実際に仕事で使ったときに自分達ルールというか、非プログラマでもドキュメント作成できるような環境のお膳立てをしました。優れている点は

  • テキストエディタで作成可能
    Windows/Mac/Linux 関係なく利用可能
  • 非プログラマでも簡単に習得可能
    ドキュメントに合わせたtoctreeとファイル群を事前に用意。担当にテキスト作成を依頼するだけ。
  • シンプルでさくさく書けること
    仕事で利用する場合雛形を事前に作成、最低限の書式のみというルール。ドキュメント作成者の技術スキルに関係なく文書作成だけに集中してもりもり作成してもらえる。
  • 図の修正が簡単(苦痛がない、これは結構重要)
    Excelの描画ツールではなく、図の描画は専用ツール使おうよ。と思っている。
  • 見た目重視の図、複雑な図ははじめから専用ツール(visio,Omnigraffle)を利用

自分の要求を満たした Sphinx + blockdiag という組み合わせはおすすめです。

次回のエントリは @togakushi です。お楽しみに。

Sphinx + blockdiag による非プログラマのための使える図解の紹介」への1件のフィードバック

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください