ドキュメント化のススメ - ドキュメント作成が苦手なアナタに

エムスリーキャリアでWebエンジニアやっている諸岡(morooka_cube)と申します。現在は薬局向けBtoBサービスのリニューアル案件に携わっています。

先日、開発ツールのレビューサイトFindy Toolsにて、データ基盤構築ツールTROCCOの記事を寄稿しました。

最近のマイトレンドはHotwireとdbtとショッピングモール巡りです。

休日のプライベートな作業や情報収集する時、自宅だと捗らないという方いませんか?そんな時の気分転換にショッピングモール巡りがおすすめです!

スタバでマック

(このブログもショッピングモール巡りがてら「スタバでマック」スタイルで書いてます)

 

ドキュメント化に取り組む以前の状況

私自身、ドキュメント化に対しては消極的な姿勢でした。

  • 実装スピードに自信があり、かつドキュメント化は面倒で時間のかかる作業と思い込んで相対的にドキュメントを軽視していた
  • Word・Excelで書かれた網羅的なドキュメントに対するアレルギー反応
  • ドキュメントが効果的に働いているプロジェクトに関わったことがなかった

等が要因として挙げられます。要するに私もドキュメント作成が苦手です!!!

そして現在担当しているサービス自体もこのような状況だったので、リニューアル案件を進めるにあたり以下の課題が発生していました。

  • ビジネスロジックのあいまい化・複雑化
    • 設計・実装の前提となるロジックが明確になっていない
    • コードリーディングしたり本番環境を動かして理解する必要あり
    • このような状態で追加改修をミルフィーユのように積み上げてきたので、リファクタリングしようにも「触らぬ神クラスに祟りなし」状態
  • 関係者間のコミュニケーションコスト増加
    • リニューアル案件に際しビジネスサイド・エンジニアともに関係者を増員
    • 複雑なビジネスロジックのキャッチアップに追われる
    • 既存メンバーであっても誤解や要件漏れを起こすため、コミュニケーションの齟齬原因に
  • 要件定義・仕様設計の手戻り
    • 現状仕様の理解が浅い・共通認識が取れていない状態で要件定義・仕様設計
    • 実装フェーズに入ってようやく考慮漏れに気付き、要件定義のやり直し
    • 最悪のケースとして「これは特殊パターンだから設計変更ではなくコーディングの工夫で乗り切ろう」でバグの温床
    • 既存機能に関しても穴が見つかり、「スコープ広げてイチから再設計したほうがいいのでは?」なんてことも

ドキュメント化に向き合ってみて得られたこと

ドキュメント手法に対する「食わず嫌い」状態から、見様見真似でやってみたところ以下のような効果が得られました。

  • 関係者間コミュニケーションの改善
    • チーム内や関係者間のコミュニケーションがスムーズに
    • 要件や仕様の誤解防止
  • 要件定義の進捗改善
    • 「ここの要件は記入まだ・MTGで詰める」等メモを残すことで進捗の見える化・考慮漏れの防止
    • 意思決定の優先順位が明確に
  • ビジネスロジックの解像度向上・簡素化
    • 手始めに現行機能のロジックや業務フローを文書化してから「どのように追加するのがベストか」ベースで検討
    • ロジック・業務フローの複雑化を防止
    • 検討した結果既存ロジック・業務フローに変更を加えることになっても、関係者への周知が簡単に

ドキュメント化のフレームワーク・ベストプラクティス

アジャイルソフトウェア開発宣言包括的なドキュメントよりも動くソフトウェア

アジャイルソフトウェア開発宣言

アジャイルソフトウェア開発宣言

はじめてこの文書を読んだ時、私は「なるほど、ドキュメントも大事だけど動くソフトウェアのほうが大事なんだな。ドキュメント化には消極的な姿勢のままで問題ないか」程度の浅い理解でした。

今は別の視点で解釈しています。

包括的なドキュメント」とは読み手の対象(経営層だったり新人プログラマーだったり)に関わらず理解できるよう情報が網羅された文書のことであり、関係者とのアジャイルなコミュニケーションができているのであれば、読み手の対象を絞った上で包括性を欠いてもよいと理解しました。

そして、アジャイルコミュニケーションの外野にいるステークホルダーに対しては、ドキュメントの納入ではなく「動くソフトウェア」を開発進捗のエビデンスとするという価値観です。

ドキュメントの網羅性は関係者とのコミュニケーション密度によって変わる

上記アジャイル開発宣言の解釈を前提とすると、「アジャイルなコミュニケーション」の実現具合によってドキュメントの適切な網羅性が変わることになります。

ビジネスサイドとの関係性ができていないプロジェクト初期は「言った・言ってない」を文書化する作業に追われるかもしれないし、逆に全ての意思決定を対面会話で済ませるほど密結合にコミュニケーションしているなら、会話の結論をメモするだけで済むかもしれません。

つまり、「ドキュメントのフォーマットを固定化するのではなく、コミュニケーション密度に応じてフォーマットを柔軟に変える」という考え方です。

状態遷移図・状態遷移表

ここまでマインドの話中心になってしまいました🙇‍♂️具体的な方法論も書きます!

先日社内のQAグループ主導でソフトウェアテスト手法の講座があり、その題材がソフトウェア設計・ドキュメント化の観点からもとても参考になったのでシェアします。

状態遷移図を書くと、「状態」「トリガー(イベント)」で考慮漏れや不整合がないか整理することができます。
また、「遷移前の状態」「トリガー」「遷移後の状態」の関係を表した状態遷移表を書くことで、あいまいな仕様や認識の齟齬を生みやすい箇所を特定することができます。

実際のシステムに適応した例

講座の中では、この状態遷移図・遷移表に以下機能を追加する演習を行いました。

「承認済み」を「再編集」することで「未申請」にすることができる
「承認済み」を再編集で「未申請」にした場合のみ以下の動作とする
 ・「取り消し」で「承認済み」に戻る
 ・「申請中」に進んだ後も「未申請」に戻れば「取り消し」可能
 ・「取り消し」後の申請内容は再編集前の状態に戻す

…文章のみだとなんだかよくわからない印象(=ビジネスロジックの解像度が低い)ですが、状態遷移図に起こすことで、「再編集」「取り消し」というトリガーを実現するために「再編集・未申請」「再編集・申請中」という新たな状態が必要になることがわかります。

「再編集・未申請」の場合は取り消し可だが、再編集ではない「未申請」の場合は取り消し不可とするため)

「再編集」「取り消し」を追加した状態遷移図

「再編集」「取り消し」を追加した状態遷移表

システム間連携時のフローチャート

システム間のデータ連携を行う機能を開発する際は、

  • 私「処理Aは対向システムがやると思ってた…」
  • 対向システム担当「処理Aはそちらがやると思ってた…」

のような認識齟齬を防ぐため、対向システムとの責務分けを明確にする必要があります。

そんな時はフローチャートを書いて「この処理は対向システムの責務」と明記するとわかりやすいです。

システム間連携時のフローチャート

生成AIの活用(情報求ム)

フレームワーク・ベストプラクティスを駆使しても、ドキュメント化は時間がかかります。

大枠を自分でプロットした上で、面倒な作業は生成AIにお任せできるといいのですが…このあたり私はまだ試せていないので、情報提供お待ちしています!

終わりに

ドキュメント化、こわくないよ!!

PlaywrightでのE2Eテストで選択できるモバイルブラウザについて

エムスリーキャリアでQAを担当している川浪です。

私は現在、医師と薬剤師向けのWebアプリケーションを提供するプロジェクトにおいてQAとして活動しています。

タイトルにもあるように、本記事ではPlaywrightでテスト実行する際に選択できるモバイルブラウザの追加方法についてご紹介します。

Playwrightとは

Playwrightは、マイクロソフトが開発・提供しているE2Eテスト自動化フレームワークです。  
https://playwright.dev/

詳細な説明は割愛しますが、Visual Studio CodeVSCode)の機能拡張(Playwright Test for VS Code)も提供されており、VSCode上でPlaywrightのスクリプトを作成・実行することができます。

 

本記事の前提条件

本記事の前提条件は以下の通りです。

 

Playwrightで動作確認できるブラウザ

Playwrightをインストールすると、以下のブラウザで動作確認ができます。

上記ブラウザはいずれもPCのブラウザとして動作するので、Playwrightの初期状態ではモバイルのブラウザで動作確認ができません。

モバイルデバイスエミュレーターでテストするには

モバイルのブラウザ(iOSSafariAndroidChrome)で動作確認するには、playwright.config.ts を開いて編集します*1

playwright.config.ts の初期状態では、以下の通りモバイルのブラウザに関してはコメントアウトされているので、コメント解除すれば利用できるようになります

    /* Test against mobile viewports. */
    // {
    //   name: 'Mobile Chrome',
    //   use: { ...devices['Pixel 5'] },
    // },
    // {
    //   name: 'Mobile Safari',
    //   use: { ...devices['iPhone 12'] },
    // },

VSCodeで選択項目に追加されていることが確認できます

 

エミュレーターの種類を増やすには?

モバイルデバイスでのE2Eテストが可能になりましたが、モバイル版ChromeはPixel 5、モバイル版SafariiPhone 12 とそれほど新しいデバイスではありません(2024年4月時点)

他にエミュレートできるブラウザはないのか?と思い調べてみると、モバイルデバイスエミュレーターは、以下のファイルで定義されていました

(Playwrightのインストールフォルダ)\node_modules\playwright-core\lib\server\deviceDescriptorsSource.json

jsonファイルを開いてみると、ポートレートモード(縦向き)とランドスケープモード(横向き)の両方が定義されているデバイスもあります

deviceDescriptorsSource.json を参照し、追加したいデバイスのキーをplaywright.config.ts に追記すれば、コメントアウト解除した以外のデバイスでも動作確認が可能です

例えば、iPhone 14 Pro を追加したい場合は下記のように追記します

    /* Test against mobile viewports. */
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'Mobile Safari',
      use: { ...devices['iPhone 12'] },
    },
    {
      name: 'Mobile Safari on iPhone 14 Pro',
      use: { ...devices['iPhone 14 Pro'] },
    },

おわりに

今回はPlaywrightでモバイルデバイスでのテスト実行についてご紹介しました。

Playwrightは、CypressやTestCafeといった先行リリースされたE2Eテストのフレームワークと比べ、動作確認できるエミュレーターの多さという意味でも利用価値が高いと考えています。

弊社のサイトはスマートフォンでの操作を前提としたWebアプリケーションが多いので、今後のQA業務でテストを自動化する際にPlaywrightの利用も視野に入れていきたいと思います。

 

*1:playwright.config.tsファイルは、Playwrightのインストール先フォルダ直下にあります

Ruby on Railsのモジュラーモノリス化 ~PackwerkとPacksRailsの導入~

こんにちは。エムスリーキャリアでエンジニアをしているakitoshigaです。

 

近年、疎結合アーキテクチャの選択肢としてモジュラーモノリスに注目が集まっていますが弊社では保有するプロダクトの1つであるM3Career Primeでモジュラーモノリス化に取り組んでいます。

 

今回はモジュラーモノリスの概要や採用に至った背景、モジュラーモノリス化における具体的な取り組みの1つであるPackwerkとPacksRailsを導入した話について紹介したいと思います。

 

M3Career Primeとは

M3career Primeとは、弊社で保有するプロダクトの1つであり医療機関を対象にした医師の採用支援SaaSです。

enzine.m3career.com

 

モジュラーモノリスとは

疎結合アーキテクチャの1形態であり、単一のコードベースで構成されていますが内部的には機能やビジネスコンテキストの単位で論理的に分割されています。

マイクロサービスと比較して個別のスケーリングやデプロイができないデメリットがあ

りつつも構築や運用コストが低いメリットがあります。

 

モジュラーモノリスアーキテクチャのイメージ図

 

なぜモジュラーモノリス化なのか?

M3Career PrimeはRuby on Railsで構築されています。

当プロダクトはサービスオープン以降度重なる機能の追加や既存機能の改修、さらには本来の機能とは無関係なLP等のサービスも単一のコードベースに追加されるようになってしまい「巨大な泥団子」と化してしまっておりました。

それにより、以下の問題を抱えていました。

  • 潜在的な依存関係
  • モデルと実装が乖離
  • 低凝集・密結合なコード
  • 属人化しており、秩序のないコード

その結果として保守性が著しく低下、仕様の調査・見積もり工数の増加、改修に時間がかかるという開発・運用上の課題を抱えていました。

さらに、当プロダクトの構想として今後新たなサービス展開が打ち出されることが予見されていました。

この構想はモジュラーモノリスアーキテクチャと相性が良く、課題解決と今後のサービス展開を見据えて当プロダクトのモジュラーモノリス化を決断しました。

 

しかし、この決定の前に葛藤もありました。

TechRachoさんが公開されている「素のRailsは十分に豊かである(翻訳)」にもある通り、大規模なサービスでも素のRailsで書かれている事例は存在しています。

techracho.bpsinc.jp

 

個人的にも、前述の問題は非アーキテクチャ依存でありリアーキテクティングまでせずともよりミクロなレベルのリファクタと「Rails Way」の徹底で開発上の課題は解決するのではないかとの思いもありました。

 

しかし、以下の理由から最終的にはモジュラーモノリスへのリアーキテクティングを実施することを決定しました。

  • 個人の経験から、アーキテクチャによる制約を設けた方が保守性を保つことができるのではないかと仮説を立てた。
  • 当プロダクトのビジネス的スピード感を考慮した時に、前述の構想に追従するためにはこのタイミングでリアーキテクティングを行うことが最適だと判断した。

 

Railsのモジュラーモノリスの実装方法にいはくつか種類があるのですが、インクリメンタルに移行出来る点と、前例の多さからPackwerk(+PacksRails)に決定しました。

 

Packwerkとは

Shopifyが開発しているパッケージ間の依存の静的解析ツールです。

Railsアプリケーション内で論理的な境界を定めることでモジュール化を支援します。

github.com

PacksRailsとは

通常のRailsから離れたディレクトリ構成にすることが可能になり、主に物理的なコードベースのモジュール化を支援します。

Packwerkと組み合わせて使用します。

github.com

 

導入した所感

リアーキテクティングにエンジニアの全リソースを注ぎ込めないため、PackwerkとPacksRailsのインクリメンタルに移行出来る点はかなり取り組みやすいと思いました。

 

PacksRailsを利用すると通常のディレクトリ構成と異なる形で開発をする必要が生じますが、そこまで大きい負荷にはなっていないと感じています。

 

最後に

現在は試験的に一部の機能を物理的にパッケージ分けした段階であり、これから本格的にモジュラーモノリス化に向けた取り組みを行っていくことになります。

 

また、モジュラーモノリスアーキテクチャの実現のためにPackwerkとPackRailsの導入以外にもいくつかの施策を実施・検討しています。

 

これらの取り組みについて、また別の機会でご紹介できればと思います。

エンジニア組織でLT大会を開催しました

こんにちは。BDEチームの近藤(atkondo)です。今月からエムスリーキャリアにてTechblogを始めさせて頂きます。

狙い、概要

 当社のエンジニア組織では、年に1回3月にLT大会を行っています。狙いとして、「エンジニア同士の活躍を讃えるとともに、役割/業務/人となりについての相互理解を深める」ということで実施しています。

  • 内容:以下についてを基本的には一人一人が発表しています。
    1. 事業に高く貢献した案件、
    2. 主に取り組んで来た案件や技術、
    3. プライベートを含めて頑張ったこと
  • 参加者:全体で60名の参加、発表は4月予定の新卒の方や入社後一定期間が経過していない方等を除く、46名の発表でした。一人基本4分の持ち時間で、全体で5時間半のイベントとなりました。
  • 表彰:当社では年に2回全社表彰と部門表彰が行われています。LT大会の内容をアンケートを取りその結果で、社表彰では次の3項目で1〜3位を全員のアンケートで推薦しています。
    •  M3Cの事業への貢献度(1〜3位)  
    •  エンジとして見習いたい(1〜3位)
    •  興味ある・面白いプロジェクトや技術(1〜3位)

  部門表彰では以下の3項目で全員のアンケートで選出しています。これはエンジニアの行動指針としても定めている内容となります。

    •  技術力を持って事業に踏み込む
    •  誰よりも当事者意識を持つ
    •  挑戦し続ける道を選ぶ

 

どのような発表があったか?①戦略推進チームの活躍ぶり

 Techblogということで社外の皆さんにお届けしたいと思ったのが、戦略推進チームの活躍振りです。

 戦略推進チームとは社内のキャリアコンサルタント/営業を支えるSFA/CRMシステムを担当しているチームです。SFASalesforceで構築して、SFAを中心にAI、DWHなどを連携させています。

 当社の募集要項では社内システムエンジニアという枠で募集させて頂いているメンバーが所属しているチームとなります。社内システムエンジニアというと各社で内容が異なりが大きいと思いますので、一例としてその活動内容をお伝えさせて下さい。

 

 例えば、西村さんからは「事務長の方向けのメルマガの改善」の発表を頂きました。

今年度、お客様にかなり評価を頂いた施策で、定量、定性面双方で大きな効果があったという話がありました。

 詳細は避けますが、お客様へどういった内容を届けるべきなのか?、また、その障害となり得る業務フローをどう見直すべきなのか?といったところに着目したことで成果に繋がったと言える施策であったかと思います。

 さらに、エンジニアとしての対応として以下の成果を発表されていたのが印象的でした。  

  •  開発時の工夫としてモジュール分割
  •  過去の振り返りを各工程での課題を改めて整理した上で開発に取り組む

 こまめに進めて行くことは大切だと思いました。

 

どのような発表があったか?②事業へのコミット

 もう1つお届けしたいのが、事業へコミットを行うエンジニアの活動です。

 例えば、当社では産業保険・健康経営サービスを手掛けています。その中で、「産業保険Plus+」というサービスを展開させて頂いています。

 以前からMVPとして構築していたサービスを本格展開しました。

 

 このプロジェクトの主要メンバーである苗床さんからプロジェクトの振り返りの発表を頂きました。

 体制、スケジュール、要件詰め、デザイン、開発、インフラ構成、アプリケーション構成、その他の発表とともに、無事リリースに向けて上手くいったことの発表がありました。

  • 途中ふりかえり
  • 連携・フィードバック 

 こまめに関係者間でコミュニケーションを取ることの重要性を改めて認識した発表でした。 



振り返って 

 毎年ですが当社のエンジニア組織の活躍ぶりを知ることができる貴重な場所となっています。また、メンバー同士のリアクションも頻繁で雰囲気の良い場となっています。

 

 当社は引き続き採用活動を行っています。こうしたエンジニア組織の雰囲気を知りたい方はぜひカジュアル面談でお話させて下さい。

  • エンジニア採用ページ

https://career.m3career.com/midcareer/engineer