僕は成果物をMermaidで作ることが多いです。
Mermaidとは、フローチャートにガントチャート、シーケンス図、クラス図、状態遷移図やER図など、エンジニアがよく使う様々な図表をMarkdown記法で描けるライブラリです。
QiitaやGitHub、Notionも対応しているのでご存知の方は多いと思います。
例えばシーケンス図はこんな感じに描けます。
(ちなみにこれは、Amazon Kinesis Data Firehoseが受信し別のLambdaで変換されたCSVファイルを読んでAWSのDMSタスクで扱える形式に変換するところまでを描いてみたもの)
そしてこれが、上記シーケンス図のソースコードです。
sequenceDiagram
participant SRC as S3 BUCKET<br>device-data
participant LF as lambda_function.py
participant CSV as csv_data.py
participant MD as models.py
participant SV as services.py
participant TGT as S3 BUCKET<br>sensor-data
SRC ->> +LF: ObjectCreated<br>/transform
Note over LF, CSV: sensor
LF ->> +CSV: get_as_sensor_data
CSV ->> CSV: convert
CSV -->> -LF: sensor_data
Note over LF, SV: foobar
LF ->> +CSV: get_as_foobar_data
CSV ->> +MD: sensor_no
MD ->> +SV: connection
SV ->> -MD: close
MD -->> -CSV: id, sensor
CSV -->> -LF: foobar_data
LF ->> TGT: Upload sensor_data {TARGET_OBJ_KEY}/YYYYMMDDHHMMSS.csv
LF ->> TGT: Upload foobar_data {TARGET_OBJ_KEY}/YYYYMMDDHHMMSS.csv
LF ->> -SV: commit
ガントチャートだとこんな感じ。
上記ガントチャートのソースコードです。
gantt
dateFormat HH:mm
axisFormat %H:%M
section マイルストーン
開始 : milestone, m1, 09:00, 0min
終了 : milestone, m2, 18:00, 0min
section データ<br>バックアップ
移行前 : 09:00, 3h
移行後 : 14:00, 3h
section データ通信
停止 : 12:00, 1h
section アップデート
アップデート : 13:00, 1h
section クライアント
インストール : 13:00, 2h
section ストレージ
容量確認 : 13:00, 1h
必要に応じ過去データ削除 : 14:00, 1h
section foobar
接続先登録 : 15:00, 1h
通信確認 : 16:00, 1h
section 通信再開
稼働確認 : 17:00, 1h
見栄えはCSSでカスタマイズできるので、フローチャートを応用すればネットワーク構成図なんかも描けると思います。
最初はとっつきにくいかもしれませんが、慣れるとパワポやExcelで作図するより圧倒的に楽です。
ひな型というか基本形はChatGPTに指示してコード吐かせても良いと思います。
非IT企業で「ウチはOfficeしか認めん!」という状況なら、PNG画像で出力して貼り付ければ良いのではないでしょうか。(編集できないけど…)
Mermaidを扱えるソフトは沢山ありますが、僕はVSCodeのプラグイン Markdown Preview Mermaid Support を使っています。
大企業とかで勝手にソフトをインストールできない環境なら、ブラウザベース(Webサービス)で動くMermaidもあります。公式でも Mermaid Live Editor を提供しています。