この記事ははてなエンジニアのカレンダー | Advent Calendar 2021 - Qiita 2日目の記事です。
最近、データパイプラインの整備や営業チームの人力混じりの運用フローを機械化するなどの業務改善に取り組んでいます。
その過程で、運用ドキュメントを読んだりヒアリングして図を描くことがよくあります。 描いた図をもとに「この流れであってますか?」と確認したり「ここ手間結構かかってそうですが困ってませんか?」とコミュニケーションをします。暗黙的な業務の流れが明確になるだけでなく、改善点の発見にも繋がります。
ひととおり改善タスクが終わった後にも図を最新にします。ドキュメントと併せて成果物とします。 どんなデータがあってどのようにビジネスに使われているか、データがどのように取得&保存されているかを残しておくのは今後のデータ活用や改善のためにも必要です。
俺はそんな個々の業務のデータフロー図を描いていって、やがてはおっきなエンタープライズデータモデルを絵にしたいんだ。
でも図やドキュメントを書いていく上で様々な悩みがある!!
GUI 作図ツールを使う
データフロー図を描くために、draw.io や Cacoo といった作図ツールを使ったり、Google スライド や miro といったスライドツールやホワイトボードツールを使う選択肢がある。
ツリーやダイアグラムを作るためのパーツが用意されていたり、リアルタイム同時編集できるものも多く複数人での認識合わせにも使えて大変便利だけど、いろいろ不満もある。
レイアウトにこだわりがち
自由な絵が描けるのはよいけど、レイアウトに結構な時間を使ってしまう。
ボックスの大きさは揃っているほうがよいしX軸Y軸のアラインを揃えたい、矢印は交差してほしくないし、矢印やボックスの形に一貫した意味が欲しい...とやっていると必要以上に時間を使っていることに気づく。
きれいな図は理解を助けるけど、一世一代のプレゼンテーションでもないのにこだわりすぎるのも無駄が多い。 とはいえある程度は整えないと読み解くのにストレスがあり、ちょうどよい塩梅が難しい。
一貫したルールがないと複数の図を並べた時にもごちゃごちゃした印象になってしまう。
その他いろいろ
- ドキュメントと別の所にあるので更新されなくなりがち
- えてして検索性が悪がち
- 画像として書き出したりスクリーンショットを撮ってドキュメントに移すのがダルいがち
- やる気のある1人だけがメンテナンスする羽目になりがち
- 差分管理できながち
図を作る部分の体験はよいけど、その図をどう運用していくか...というところで悩みが出てくる。
Graphviz や PlantUML を使う
普段のテキストエディタで書けて一定のクオリティの図が作れるので重宝している。 レイアウトも多少意識する面はあるものの細かく手をいれられないので適度に妥協できるのも逆に良い点。 社内 Wiki にドキュメントを書く時に、ページ下の方にソースを貼り付けてドキュメントと図のソースの距離を近くすることもできる。
一方で満たされない思いもある。
- 記法の学習コストがあるがち
- リポジトリに入れると権限が必要だったりしがち
- 特に営業チームのメンバーが利用したい時に困りがち
- 巨大な図を作るとメチャクチャになりがち
ドキュメント
ここまで図の話をしてきたけど、実際にはドキュメントの一部として図を描きたい。
この業務の背景や目的、関連するドキュメントやダッシュボードへのリンク、新たにデータを利用する際の方法、実装を行っているリポジトリ、権限や窓口、データの更新頻度や扱う諸注意...などなど、図だけで説明しきるのは難しくて、ある程度文章で説明することになる。
ドキュメントを作ってメンテしていく上で、もっとドキュメントと図を近づけたい。
Google Colaboratory でドキュメントを書く
Colaboratory は Google の提供する Jupyter Notebook & Python ランタイム。
これを使ってドキュメントを書くのはどうか、というのが今回の試みです。
データを扱うエンジニアには Jupyter はお馴染みだろうから親和性も高い。
Colaboratory へようこそ - Colaboratory
やってみます
Google Colaboratory でデータフローのドキュメントを書く試み - Colaboratory
いかがでしょうか。
果たしてまな板やすし桶はデータストアなのか、これはデータフローなのか、寿司酢を入れなくてよいのか、異論はあるだろうけどデータフロー図とドキュメントを書くことができた。
Colab を使うと
- 図のソース置き場と表示をどちらも満たせる
- Markdown を使ってドキュメントを書ける
- 環境構築にあまり煩わされない
- BigQuery など実際のデータにアクセスしてサンプルデータを表示したり可視化できる
- Google アカウントによる権限管理ができる
- Google Drive 検索にひっかかる
- 変更履歴が残り古い版に戻せる
これらのいいことがある。
やっていること
依存のインストール
! に続けてコマンドを打つことでシェルで実行される。
!apt や !pip で依存を入れることができる。
これをコピペして使っている
#@title !pip install graphviz plantuml fonts-noto-cjk
#@titleは後述- graphviz, plantuml をよく使う
- fonts-noto-cjk
- 日本語フォントに Noto Sans Japanese を入れる
- 入れないと図中に日本語が表示できないことがある
- 他のフォントウェイトは
fonts-noto-cjk-extraにあるけど大きめなので使ってない fonts-ipafontとかでも良いと思います
Graphviz や PlantUML のソースを置く
%%writefile {filename} から始まるセルを評価すると、以降の内容が filename に保存される。
Python コードで open して文字列を書いている例がよくあるけど、特定のテキストをファイルに書きたいだけならマジックコマンドを使うのが簡単。
Built-in magic commands — IPython 7.30.0 documentation
画像の生成 & 表示
単に Graphviz や PlantUML で画像を作って表示する
!dot -Tpng my-flow.dot > my-flow.png # graphviz !plantuml my-flow.puml # plantuml from IPython.display import Image Image('my-flow.png')
一旦完成したらコードを非表示にする
ドキュメントとして見せるにはコードを非表示にしておくほうが見栄えがいい。 メニューの "表示" からコードを非表示にするとセルを折りたたむことができる。
非表示にするとセルの先頭に #@title が挿入されるのは、フォームから変数に値を入れる機能を転用して非表示を実装しているからのようだ。つまりメニューを経由しなくてもセルの先頭に #@title を書いて右側の空白をダブルクリックしてもよい。
感想
どうでしょうか、Colab にドキュメントを書くのはまだお試し中ですが、悪くない気がします。
特に、ちょっとラベルを変えたり 1~2本フローを増やしたりなどの微修正は画像を生成して Wiki に貼り付けたり、リポジトリにコミットする必要もなくて気楽にできます。
コードセルを非表示にしていても余白ができるのでがちゃがちゃした見た目になりがちだったり、Colab に詳細めなドキュメントが描いてあるという期待がないので社内 Wiki からリンクしていても読まれにくい、という点は気になる。
データアーキテクチャを図にしたりドキュメントにする良いツールやプラクティスがあれば教えて下さい。
アドベントカレンダーについて
はてなエンジニアのカレンダー | Advent Calendar 2021 - Qiita
前日は 
id:nanto_vi による HTMLのdialog要素とフォーム機能 - Hatena Developer Blog でした。
明日は 
id:gurrium さんの WoTのMODを作りたい - ぜのぜ です。
