Gaugeで学ぶ実行可能ドキュメントの価値

3K Views

November 26, 22

スライド概要

JJUG CCC 2022 Fall でのスポンサーセッション『Gaugeで学ぶ実行可能ドキュメントの価値』の発表資料です。

profile-image

シンプレクスは1997年の創業以来、メガバンクや大手総合証券を筆頭に、日本を代表する金融機関のテクノロジーパートナーとしてビジネスを展開してきました。現在では、金融領域で培った豊富なノウハウを活用し、金融機関以外の領域でもソリューションを展開しています。2019年3月にはAI企業のDeep Percept株式会社、2021年4月には総合コンサルティングファームのXspear Consulting株式会社がグループに加わり、創業時より付加価値の創造に取り組んできたシンプレクスとワンチームとなって、公的機関や金融機関、各業界をリードする企業のデジタルトランスフォーメーション(DX)の推進を支援しています。

シェア

埋め込む »CMSなどでJSが使えない場合

関連スライド

各ページのテキスト
1.

gaugeで学ぶ実⾏可能ドキュメントの価値 シンプレクス株式会社 清家蒼⼀朗 JJUG CCC 2022 Fall 1

2.

Learning Outcome • 実⾏可能ドキュメントとは • gaugeを使ったドキュメント作成⽅法 • 新しいアイデアをチームに導⼊するステップ 2

3.

Agenda • ⾃⼰紹介/シンプレクスについて • 現場の課題 • 実⾏可能ドキュメント • gaugeの推しポイント • gauge導⼊に際して • まとめ 3

4.

⾃⼰紹介 清家蒼⼀朗 Soichiro Seike 所属 シンプレクス株式会社 開発担当 ⾦融商品取引プロダクトチーム 使⽤する Java 技術要素 JavaScript(React.js, TypeScript) AWS 4

5.

シンプレクスについて 1997年創業のITコンサルティング企業 IT戦略から開発、運⽤まで⼀気通貫で担い、トータルソリューションを提供 して います 創業当時より ⾦融フロント・ミドル領域 に強みを持ち、市場業務、リテール⾦融 業務に多数の実績 2013年より 保険領域 にビジネス拡⼤し、現在に⾄るまで実績多数 各種領域で ⾃社パッケージ・フレームワーク・ライブラリの開発・活⽤ により業 界知識集約・⽣産性向上を図っています 近年は⾮⾦融領域へもビジネスを展開しています 5

6.

所属チームのプロダクトについて • toB向けの⾦融商品取引プロダクト • シンプレクスの蓄積してきた業務知識、お客様の課題ヒアリングをベースに、 より良いプロダクトを⽬指し、チームをスケールさせながら機能アップデート を進めている 6

7.

現場の課題 機能仕様調査に潜むムダ 7

8.

チーム内の仕様確認 A機能って、Bの状況の場合は、Cという動きになりますよね? という問い合わせが来たんですけど、ドキュメントには記載がなく て、、 誰かわかりますか? 基本はそうだね。 でも、BかつDの状況だと、Cという動きにはならなかったような。。 最近A機能って仕様変更あったような。。今も本当に記憶通り動く かな? テスト環境で再現した方が確実な回答ができるね。 8

9.

チーム内の仕様確認 【課題】 ・詳細な仕様知識の属人化 ・信頼できる情報の欠如 正確な仕様を迅速に把握するために A機能って、Bの状況の場合は、Cという動きになりますよね? もっと改善できることがあるのでは? という問い合わせが来たんですけど、ドキュメントには記載がなく て、、 誰かわかりますか? 基本はそうだね。 でも、BかつDの状況だと、Cという動きにはならなかったような。。 最近A機能って仕様変更あったような。。今も本当に記憶通り動く かな? テスト環境で再現した方が確実な回答ができるね。 9

10.

チーム内の仕様確認 【課題】 ・詳細な仕様知識の属人化 ・信頼できる情報の欠如 正確な仕様を迅速に把握するために A機能って、Bの状況の場合は、Cという動きになりますよね? もっと改善できることがあるのでは? という問い合わせが来たんですけど、ドキュメントには記載がなく て、、 誰かわかりますか? 信頼できる形式知が必要 基本はそうだね。 でも、BかつDの状況だと、Cという動きにはならなかったような。。 最近A機能って仕様変更あったような。。今も本当に記憶通り動く かな? テスト環境で再現した方が確実な回答ができるね。 10

11.

Executable Documentation (実⾏可能なドキュメント) 11

12.

実⾏可能ドキュメント ⾮エンジニアが理解できる⾔語での仕様記述と、 実⾏可能なテストコードがセットになったドキュメント 12

13.

実⾏可能ドキュメント ⾮エンジニアが理解できる⾔語での仕様記述と、 実⾏可能なテストコードがセットになったドキュメント ドキュメントと実際の振る舞いに差が⽣まれたことを検知できる 13

14.

実⾏可能ドキュメントに期待すること • ドキュメントの読者が情報の劣化を⼼配することなく、読むこ とができる • 開発者はメンテナンスされなくなるかもしれない不安から解 放されて有益な形式知を作成できる 14

15.

gauge 15

16.

gaugeについて • ThoughtWorks社製OSSの実⾏可能ドキュメント作成フ レームワーク。 • Markdownで⾃由に記述が可能。 • Java、Ruby、Javascript、C#、Pythonで記述可能。 16

17.

gaugeについて Spec(仕様書) 先頭の⽂字列を*にすると、テストケースとして 認識される ※発表向けのサンプルコードです 17

18.

gaugeについて Step(テストコード) テストケースをどのように実現するか は⾃由。 ※発表向けのサンプルコードです 18

19.

gaugeの使いやすいポイント ①: 形式的な書き⽅/読み⽅を強制されず、導⼊のハードルが 低い ②: ビルドツールへの統合プラグインが開発されており、継続的 なテストを⾏う環境の構築がしやすい 19

20.

gaugeの使いやすいポイント ①: 形式的な書き⽅/読み⽅を強制されず、導⼊のハードルが 低い ②: ビルドツールへの統合プラグインが開発されており、継続的 なテストを⾏う環境の構築がしやすい 20

21.

gaugeの使いやすいポイント 例えばCucumberのfeatureファイル ※発表向けのサンプルコードです 21

22.

gaugeの使いやすいポイント gaugeのmarkdown 機能の概要/目的、入出力バリエーションの網羅 度を表現するテーブルなども自由に記載可能。 ※発表向けのサンプルコードです 22

23.

gaugeの使いやすいポイント htmlドキュメント⽣成 プラグインを使えば、目次を含めたhtmlドキュメント を生成できる ※発表向けのサンプルコードです 23

24.

gaugeの使いやすいポイント htmlドキュメント⽣成 ※発表向けのサンプルコードです 24

25.

gaugeの使いやすいポイント ①: 形式的な書き⽅/読み⽅を強制されず、導⼊のハードルが 低い ②: ビルドツールへの統合プラグインが開発されており、継続的 なテストを⾏う環境の構築がしやすい 25

26.

gaugeの使いやすいポイント 各種ビルドツールから実⾏可能 26

27.

gaugeの使いやすいポイント Dockerでのイメージ提供 27

28.

シンプレクスでの継続的テスト & ドキュメントの⽣成環境 ビルド結果のDocumentを配置し、 静的ホスティング S3 テスト環境 gaugeで記述した仕様に従い REST APIのテストを実⾏ Jenkinsおよびびそのロゴは、LF CHARITIES, INC.の⽶国及びその他の国における登録商標または商標です。 Mavenおよびそのロゴは、Apache Software Foundationの⽶国及びその他の国における登録商標または商標です。 gaugeおよびそのロゴは、ThoughtWorks Inc.の⽶国及びその他の国における登録商標または商標です。 28

29.

なぜREST APIをテスト対象にしたのか 理想的な⾃動テストのピラミッド UI Test Integration Test 上に行くほど ・メンテコストは高い ・ユーザに近いテスト ・実行速度は遅い Unit Test 29

30.

なぜREST APIをテスト対象にしたのか チームの⾃動テストのピラミッド UI Test 上に行くほど ・メンテコストは高い ・ユーザに近いテスト ・実行速度は遅い Unit Test 30

31.

なぜREST APIをテスト対象にしたのか チームの⾃動テストのピラミッド UI Testは少数にとどめなければ メンテコストの方が高くなる。 REST APIをテストできるようにし、 ドキュメンテーションすることにした。 UI Test 上に行くほど ・メンテコストは高い ・ユーザに近いテスト ・実行速度は遅い Unit Test 31

32.

REST-assuredについて REST-assured JavaでREST APIのテストを簡潔に記述するための OSSフレームワーク 32

33.

REST-assuredについて REST APIの実行、assertまでを Given/When/Thenで記述可能 ※発表向けのサンプルコードです 33

34.

gaugeの導⼊に際して 新しいアイデアをチームで試すには︖ 34

35.

gaugeの導⼊に際して 35

36.

gaugeの導⼊に際して 気をつけなければならないこと • 強いるのではなく、共感によって変化を起こす • 種を蒔いて、⽔をやることで、はじめて変化を起こせる 36

37.

gaugeの導⼊に際して 導⼊までのステップ • 動き始めるためにあらゆる準備を • 有志でのお試し活動 • 少しづつ進む 37

38.

gaugeの導⼊に際して 動き始めるためにあらゆる準備を チームにとって良い変化をもたらすものだと⾃分が⼀番に信じ、⾏ 動で⽰す。 • gaugeを継続的にテストできる環境の構築 • gaugeのセットアップ⼿順/セットアップを簡略化するスクリプト • 最もシンプルなテストケースの作成 38

39.

gaugeの導⼊に際して 有志でのお試し活動 アーリーアダプターを巻き込み、アイデアを試してみて、学習を深める。 ⼀⼈でも⼆⼈でも仲間が増えれば、より多くの発⾒が⾒つかる。 • gaugeを使って解決したい課題と、gaugeについて紹介する • 定期的にモブプロでドキュメント作成を⾏うコミュニティを作る 39

40.

gaugeの導⼊に際して 少しづつ進む 短期的な⽬標を1つずつクリアしていくことで、定期的に⾃分達の⾏動を 振り返る。⼀気に⾼い⽬標のために動き出すと振り返る機会が少ないゆ えに形骸化したり、遠すぎる⽬標に届かず挫折の原因になる。 • まずはよく問い合わせのくる機能に絞ってドキュメンテーション 40

41.

gaugeの導⼊に際して ⽬指したい姿 チームとして決めたことだからやる ではなく アイデアに共感する仲間になってもらう 無理なく、楽しく、⻑続きする⽂化になる 41

42.

まとめ • プロダクト仕様の暗黙知化、情報の信頼性の⽋如に実⾏可能ドキュ メントで⽴ち向かう • gaugeは実⾏可能な仕様書を作成するためのツール。Markdown での仕様記述が可能でドキュメント⽣成も充実しており、記述/読解 のハードルが低い。 • 新しいアイデアを組織に浸透させるにはツールの紹介だけでは不⼗分。 できる限りの準備と、継続的にアイデアを浸透させる活動が必要。 42

43.

ご清聴ありがとうございました。 43