JaSST'21 Hokkaido
Markdown+plantUMLで保守性の高いドキュメンテーションをしよう！

株式会社NTTデータ
技術革新統括本部 システム技術本部 生産技術部
ソフトウェア技術センタ
熊川 一平 イノベータ(ソフトウェアプロセス)
情報種別：公開

会社名：NTTデータ

情報所有者：技術革新統括本部

1

熊川 一平
株式会社NTTデータ
主にソフトウェアテスト/品質保証のスペシャリストとして、R&Dや現場支援に従事
外部活動
JaSST Tokyoでは3度ベストスピーカーをいただきました
JaSST'14
JaSST'19
JaSST'21

2

本セッションのねらい
ソフトウェア開発にまつわるドキュメントをExcelやPowerpointなどで作って苦労しているあなたにもっと効率的に気持ちよく作業できることを知ってもらう3アイスブレイク

4

Excel方眼紙あるある言いたい(10min)
これからZoomのブレイクアウトルーム機能を使って、皆さんを3～4名ぐらいの小グループに分けます。
簡単な自己紹介の後、1人ずつ以下の話をしてください。
参加の動機
ドキュメンテーションでこれまでに苦労したこと
Excel方眼紙への恨み、つらみ
実際のワークをする前に気持ちをアゲておきましょう5本ワークショップの流れ
6

スケジュール
時間

やること

15:15
～
15:40

プレインテキストでドキュメンテーションを行う背景やメリットを理解しよう

15:40
～
17:00

実際にドキュメントを書いて、ワークフローがどう変わるか体験してみましょう

17:00
～
17:15

FAQと振り返りを通じて学んだことを整理しましょう7

参加条件のおさらい
ワークでは皆さんにドキュメンテーションを実践してもらいます
事前の案内に沿って環境構築はできていますよね？
vsCode + Markdown preview enhanced + java +graphviz
できていなければ、最初のお話の裏でやっておいてく
ださい
8Excel方眼紙などでドキュメンテーションする際の問題点
9※WYSIWYG : What You See Is What You Get (見たままが得られる)

10

11

12

プレインテキストでドキュメンテーションしよう
13

14

Markdownプレーンテキスト形式の軽量マークアップ言語
見出し、段落、改行、箇条書き、太字、引用、表、etc…
文書作成に必要な装飾は一通りそろっています。
Githubなど、多くのサービスで利用可能
統一仕様としてCommonMarkがあるが、絵文字などの追加機能をもった方言が数多く存在する。
(e.g.GithubFlavoredMarkdown)
似たものにAsciiDocなどが存在
markdownを活用したソリューションも多数存在する。
実はこのスライドもmarkdownで作られています。
15

16

PlantUML
オープンソースのテキストでUML図形を書けるツール
テキスト形式で動作も軽量。
UMLだけでなく様々な図形に対応。
描写にはGraphvizを使用。
.puファイルとして独立して作成する他、Markdownの中に埋め込むことも可能。
最近はDiagram as a Codeなどと呼ばれることもあり、周辺ツールなどの開発も活況。
17

18

プレインテキストを使ったドキュメンテーションのメリット
Gitで管理できるテキストだからソースと同じようにGitで管理できる。
ワークフローを作れる
プルリクエストを通じて必ず承認行為が伴う差分が見れる
プルリクエストで差分を見ながらレビューもできる。
検索できる
全文検索やGrepで図内のテキストも含めて検索可能。
修正が容易
キャンバスの大きさやセルの形を意識しなくてよい。 1 9

実際に手を動かして効果を実感していきましょう
書き方はこのあたりを参考に
Markdownの仕様
https://commonmark.org/help/
https://shd101wyy.github.io/markdown-previewenhanced/#/plantUMLの仕様や例
https://plantuml.com/ja/
https://real-world-plantuml.com/
20

plantUMLをmarkdownに埋め込むには？
markdownの中で以下のように記述すればよいです。

21

ワークに関する事前説明
ワークに必要なファイルなどはdiscordで配布します
各ワークでは、まずお題に沿って個々人/グループで取り組みをしてもらいます
取り組みの後、何名かの方に感想などをお伺いしつつ、このワークを通じて伝えたかったことを共有します。
上記が完了した後、回答例を配布します。
22

ワークその１
作業時間 15min
情報共有 5min23状態遷移図を書いてみよう「work1.md」には状態遷移に関する仕様について、ディスカッションした記録が書いてあります。
記録を読んで、plantUMLを使って状態遷移図を書いてみましょう。
１つ１つの座席の状態がどのように遷移していくかを表しましょう。
24

回答例
この通りである必要はない
あまり見た目にこだわらない25

ワークその２
作業時間 10min
情報共有 5min26

シーケンス図を修正してみよう「work2_uml.md」にとあるアプリケーションの通信仕様が記載されています。
「work2.md」には通信シーケンスに関する仕様について、ディスカッションした記録が書いてあります。
記録を読んで、シーケンス図を修正してみましょう。
27

回答例
この通りである必要はない
検索・置換を行うとすぐに修正できたはず28

ワークその３
作業時間 10min
情報共有 5min29

ワーク２の結果をレビューしよう
皆様を2～3名のブレイクアウトルームに分けます。
ルーム内の参加者から代表者を1名決めてください。
代表者の方は、ワーク2の結果について、修正前後のdiffをとって画面共有しましょう。(念のため修正前ファイルも配布します。)
代表者以外の人は、修正が抜け漏れなく実施されているか、diffの結果を見てレビューしてみてください。
時間が余ったら、こうしたレビューのスタイルに関するメリットやデメリットについて参加者で話し合ってみま30
しょう。

ワークその４
作業時間 25min
情報共有 5min31

レビューコメントへの対応をしましょう
github上に修正作業中の資材があります。
URLなどは演習フォルダに配置しております
どうやら仕様変更が発生していて、plantUMLの修正がされているようですが、仕様の穴が見つかっていて、指摘を受けていますね。
指摘コメントはgithubにログインしないと見れません。
あなたが引き継いで修正をしてあげてください。
実際にpushするところまではしなくてよいです。（ロー32
カルで修正するまででよいです）

回答例
別紙(work4_uml_example.md)参照
ちょっと考えてみよう
これがパワポの狭いキャンバスに書かれていたら？
Github上でのコメントの管理について

33

まとめと振り返り34

プレインテキストを使ったドキュメンテーションのメリット
Gitで管理できるテキストだからソースと同じようにGitで管理できる。
ワークフローを作れる
プルリクエストを通じて必ず承認行為が伴う差分が見れる
プルリクエストで差分を見ながらレビューもできる。
検索できる
全文検索やGrepで図内のテキストも含めて検索可能。
修正が容易
キャンバスの大きさやセルの形を意識しなくてよい。 3 5今日学んだこと
markdownやplantUMLは怖くない
テキスト化することに多くのメリットがある

明日からやること
とりあえず何でもExcelを開く癖があるならやめる
文書も資産なのでちゃんとGitで管理する
本ワークショップで得たことを布教する
36

Question?

37