Excel設計書を抹殺したくて4年前にWiki設計書を導入したら、意外とちゃんと開発回ってた話。

8853 ワード
設計 開発環境 Excel Excel方眼紙 plantuml Excel テキストリンク

初めましてこんにちは。
最近コードレビューの記事書いたら、Excelベースだったことを理由に
Qiitaコメントとはてブで徹底的に燃やされたおじさんです。

いやね、僕だって使いたくて使ってるわけではなくてね、
できることなら使いたくないんですよ。
というわけで名誉挽回のために脱Excelできた話、
それも日本の三大悪三大風習に数えられるExcel設計書を抹殺した話を書きます。
(2/25修正：悪は言いすぎました。訂正します。）

Growi 最高。

Excel設計書

またの名をExcel方眼紙。
エクセルのセルの縦横を同じくらいの大きさに調整し方眼紙のようにして、
そこに設計書として文字と図と表を記載する方式。

メリット

  • 一つのファイルに文字と図と表がまとめて記載できる
    • テキストでは文字は書けても図と表が書けない
    • Wordでは、文字と図表エリアとを2列表示するのが難しい
      できなくはないが面倒くさい
    • UMLモデリングツールは、図は書けるが、表と文字は別ファイルで用意しないといけない
  • 比較的WYSIWYGである
    • 設計書の印刷＆レビューが必要だった時代には必須の概念
  • 設計の重要な要素である表（ディシジョンテーブル、スキーマ表等）が
    あらゆるツールの中で一番書きやすい
  • Excelの使い方は、みんな知ってて学習コストがかからない

デメリット

  • 重い
    • ちょっと参照しようとして開くのが重くて待たされる
    • そもそもファイルサイズが肥大化して重い
  • 検索性が悪い
    • 最近解消されたけど、図形の中の文字列を検索できない
    • ファイルをまたいだ検索ができない
  • 実は意外とWYSIWYGではない
    • なにげに印刷すると文字が切れたりする
    • (まぁもう設計書を印刷することもないのでいいですが)
  • 過去のバージョンに戻しづらい
    • xxxxxxxx_20200223.xlsx みたいなファイルが大量生産されてもそれは困る

発生する問題

  • 重いので開かなくなる・見なくなる
    • 追加開発時に参照されない・設計書が使い捨てになる
  • 検索性が悪いので、作った人に聞くがベターな解決策になる
    • 将来を見据えて設計するモチベーションがわかなくなる
    • 設計書ではなく、実装メモに堕落していく　
  • なくなる、どれが最新かわからなくなる
    • ファイルなので、あれ？どこいった？ということが起こる
    • ファイル名を信じればいいのか、タイムスタンプを信じればいいのか

そんな殺伐とした開発環境に、Growiが！！


（4年前はCrowi-Plusという名前でした）

Growi は 株式会社 WESEEKがオープンソースで開発しているWikiシステムになります。

Growi が 設計書システムとして優秀なところ

とにかく速い

文章の保存も、検索も爆速です。閲覧も作成も修正も、ストレスフリーで書けます。
elasticSearchを使っていて、登録したばかりのページも即検索可能です。

差分管理ができる

マークダウンの"表が書きづらい問題"を補助ツールが解決！！

plantuml と連携して、markdown で UMLが記述できる

サーバスペックにもよりますが、割と高速に画像生成されます。
また、テキストで図を記述しているので、Excelと違って差分管理ができます。

環境構築がかんたん

Windows 10 でも、Linuxでも、AWSでも、Docker環境が整っていれば、簡単に構築が可能。
(構築手順については、後述)

Growiを入れてどうなったか

  • よかった点
    • Excelの時とくらべて（表を除いて）サクサクっと書けてしまう
      • 時間は計測していないのでなんとも言えないが、
        ストレスは相当軽減されているはず
    • 20年物の自社パッケージですが、
      導入以後の設計書はすべてWiki化され、脱エクセルに成功。
      • すでに数百ページの設計がWikiで作成される
    • リリース済み機能の設計が迅速に検索・閲覧可能になった
  • そうでもなかった点
    • 設計担当者的には、Wikiでほとんど問題なかったが、
      表の記述だけは、Excel時代と比べてストレスが上がった
      • 最新のGrowiでは、マークダウンで表が書きづらい・修正しづらい問題への
        補助機能を提供しているので、この問題は現在は解消されている
    • いきなりWiki化したので、Excel時代に記述フォーマットが飛び、
      記載レベルが個人依存となった
      • 設計書で何を記述すべきかは、Growiのテンプレート機能を使って解消可能
    • 思った以上に、PlantUmlの記載が進まない
      • 独特なPlantUml記法の習熟には時間がかかる
      • これは地道にやるしかない

問題もあったけど、Excel脱却成功しました。

設計内容のプルリク的なことができれば、
設計書システムとして割と完璧になるかなと思います。

Growi導入手順

まずDocker環境を用意しましょう。

Windows 10のPCのローカルに建てる場合は、こちらを参照
Mac のローカルの場合はこちらを参照
CentOS に建てる場合はこちらを参照

※Hyper-Vとかで用意されたWindows仮想マシンにDockerを載せるのは、
※VM on VM みたいになって、そこそこ設定が必要なのでお勧めしません。

Growiをダウンロードする

公式Docsに従って、GitからCloneする

git clone https://github.com/weseek/growi-docker-compose.git growi

plantumlを使えるようdocker-compose.yml を修正する

docker-compose.ymlの23行目
-       # - PLANTUML_URI= # activate this line and specify if you use your own PlantUML server rather than public plantuml.com
+       - PLANTUML_URI=http://localhost:8080/  # activate this line and specify if you use your own PlantUML server rather than public plantuml.com
docker-compose.ymlの60行目あたり
+  plantumlserver:
+    image: plantuml/plantuml-server:jetty
+    restart: unless-stopped
+    ports:
+      - "8080:8080"

compose up する

cd growi
docker-compose up

以上。超簡単。
初回起動はもろもろdockerイメージを2GB超ダウンロードしたりするので、10分くらい待つ必要がある。

想定問答集

  • .md ファイルで作成して、githubに上げればプルリクできるし、WEBで閲覧できるし、Growiって必要？
    PlantUMLもPegmatite入れれば、描画できるし
    • 表がね・・・
    • あと本文では書いてないけど、画像貼るのが生マークダウンだと意外と面倒
      • Growiは、Qiitaみたいに、D&Dで画像貼れたり、 Win+Shift+S でキャプって、そのままCtrl+Vで貼れたりする
      • 生マークダウンは、画像保存して相対パス書いて・・・っていうのが
      • 画像の資材管理の面倒も生まれるし・・・
    • ただ、プルリクの魅力は捨てがたいので、どっちとるかはもう好みの問題かな
  • Excelでも差分とれるし、Grepもできますよ！
    • Winmergeのあれはとれたうちに入らないし、マクロGrepは遅すぎて話になりません
    • どっちもやむに已まれず使ってるけど、可能なら使いたくない
  • 印刷・納品とかどうするの？
    • うーん・・・。正直考慮外でした。現職がWEB系かつユーザ部門とのお仕事だからか、
      あまり設計書の納品が重視されないので気にしてませんでした。
    • ただ最近、画面イメージをAdobeXD、課題管理をBacklogでするというのを、
      お客様は意外とすんなり受け入れてくれるので、Wikiで作成して納品という方式も言ってみる価値はあるかと思います。
  • 行政、公共団体なんですが
    • すいませんでした。忘れてください。
  • エクセルそんなにダメか？親でも殺されたの？
    • うん。僕も結構この「エクセル辞めたい⇒なんやかんやエクセル優秀だよね」のループを 20周ぐらいしているので、実はそんなに嫌いではないんですよね。
    • まず、普及率の高さとだれでも使える汎用性は抜群ですしね。
    • 結局、納品とか誰が書き・誰が閲覧するか、どういった経験を持ったチーム・ステークホルダーか
      によって何が最適かは変わってくるんだと思います。
  • 自分らで保守するOSSは大変でしょ？Confluence使えばいいじゃん
    • Confluence知りませんでした！
    • ちょっと調べたらUMLもテキストで書けるし、Plantumlプラグインもあるみたいですね！
    • これもいいかもしれませんね！
  • PlantUMLをExcelの代わりにするのは無理なんじゃない？
    • 作図という意味で言うと無理ですよ
    • その代わり余計なことができない、余計なデザインをさせないという逆転のメリットがあります。
  • ツールはぶっちゃけなんでもいい
    • うそでしょ？メールとFAX続けますか？
  • 周りが理解してくれるのもすごい
    • いや、ほんとマジそれです。僕はきっかけで本当の改革者は実行に移したメンバーです。
  • googleスプレッドシートの共有だとどうなんだろ
    • 僕の環境だとめっちゃ重いんですけど、皆さんそうでもないんでしょうか？
  • ネットワークが死ぬと仕事できないリスク
    • 現職はそもそもファイルサーバにプロジェクトドキュメント置いてあるので、
      どっちにしろ死ぬという判断でした。
  • こういうモダンなwikiシステム入れようとするとき、IEがマジで邪魔
    • アイツはもう消した！（AA略
    • 現職は結構前にサポート終了宣言しました。
    • Win10になったら、Edgeが標準だし、EdgeもChrominiumだし