ドキュメンテーションジャーニー 〜 シフトレフト・Wモデルにちょっとでも近づける

この記事は Akerunのカレンダー | Advent Calendar 2023 - Qiita 4日目の記事です。

ishturk - Qiita です。フォトシンスに入社してもうすぐ8年になります。

この記事では、ベンチャー開発から組織的な開発に移り変わる過程で、ドキュメンテーションの実践と啓蒙した内容をまとめてみました。

昔話

ぼくが入社した2016年は開発が10人もいない小さな1チームでした。 この人数でメカ・エレキ・ファームウェア・モバイルアプリ・Webフロント・Webバックエンド・インフラ全部やってたのだから、すごいパワー。 2018年くらいまでは、スピード最優先！感動体験を大きく・早く届ける！が最重要でした。

ベンチャースピード開発あるある

ぼくが入社したとき、設計書なるものがほぼない状態で開発されていて、驚愕したのを覚えています。ぼくが最初に取り組んだのは、

を始めにドキュメント化し、FW・モバイル・Web メンバーにこれだけは常に正しい状態にしてくれとお願いしました。

逆に、ドキュメンテーションを必須化しなかったのは

  • 機能仕様・振る舞い
  • SWの構造

です。理由はいくつかありますが、主な理由は ドキュメンテーションもトレーニングが必要 で、スピード最優先！の制約では、実現不可能と判断しました。ベンチャー気質なエンジニアのスキルセット（実装の手は速いがドキュメンテーションのモチベーションが低い）もこの判断を加速させました。

でした。

今

組織も大きくなりました。それぞれのレイヤーに中規模なチームが存在し、テスト設計も専門のチームで行える体制になりました。 メンバーも、古参、中途で入ったシニアクラス、有望な若手、新卒、など様々です。

ドキュメンテーションを今進めなくちゃいけない理由

主に２つです。

開発と評価のチーム分離

テスト設計から遂行までおこない、品質に責任をもつSWQAチームが立ち上がりました。当初は手探りで行っていましたが、実動作が正しいというアンバランスから、開発サイドとSAWQAがフェアな関係性にならない課題がありました。

実装から設計の手戻り

以前は1人で全体を設計・実装していましたが、リーダー＋1〜2名という体制で開発ができるようになりました。複数人で1プロダクトを開発するので、チーム内で合意された設計があって初めて実装に進むことができる（はず）。ですが、ドキュメントが無いと合意形成の拠り所がなく、実装で設計を見直すというエンドレスワルツになります。

取り組みの狙い

  • シフトレフト・Vモデル に則り、開発全体のコストを下げる

言わずもがなです。不具合は上流工程で潰すほど、トータルコストが小さいという常識。

  • シフトレフト・Wモデル の意識をメンバーに根付かせる

バックグラウンドも様々なメンバーが多いので、共通認識をつくる必要がありました。実装と設計を同時並行のほうが速い・実装が終わらないと仕様が決められないというアンチパターンがまかり通ってしまうこともありました。理論だけ説明しても、机上の空論になってしまうので、実践してもらうことで効果を体感してもらうことを狙いました。

ドキュメンテーションにも一定スキル・経験が必要です。 開発を通してスキルアップができないと組織は成長できなく、新卒・ジュニアメンバーも多いので、開発を通じてドキュメンテーションスキルが身につく組織にするねらいです。 設計実装ができて半人前、ドキュメンテーションができて一人前。

機能仕様書

はじめに 機能・非機能仕様書 を作成してもらいました。SWQAチームが過去の経験からテストベースにしやすい雛形で、実動作をリファレンスとして作成してもらいました。 これに開発チーム・有識者がより詳細な情報を加筆することで完成させました。

これによって、テスト設計をするための情報が設計工程より前に切り出すことができました。これは狙い通りの成果です。

機能仕様書の変更を悪としない

受託等の開発では、機能仕様書をバイブルとして扱うかもしれませんが、弊社の体制では、機能仕様書の加筆・修正を推進しました。 変更できないものになってしまうと、存在が鬱陶しいものになってしまい、メンテされなくなるというアンチパターンにハマります（経験則）

たとえば、コーナーケースで記載どおりの振る舞いにならないケースや、性能が条件に依って未達になることが評価の過程でわかる、など。 仕様の変更・合意形成を素早いサイクルで回し、積極的に活用しやすい状態に育てることで、SWQA・開発のメンバーも頻繁に参照する状態になります。

プロジェクトをリードしているロールが、常にドキュメントの内容を引き合いに出すことが重要です。

SWの構造（クラス・内部シーケンス）

エンジニアはコードを書きたがる生き物です。これをグッとこらえて、クラス・内部シーケンス を作成することをルール化しました。 最初はとても時間がかかりましたが、作成者・レビュアー双方のトレーニングでプロジェクトの後半では効率があがりました。

設計通りの実装にならないなら、設計に立ち戻る

客観的にみると至極当然のことですが、実装時はよりよいコードを書くことに注力するので、案外難しいことだったりします。ここではレビュアーが重要な役割を担います。 レビュアーは設計を参照してレビューすることを徹底する必要があり、設計と乖離するなら、まずは設計変更をレビューするルールにします。

実際に以下の効果を感じました。

  • 設計書を参照できるので、レビュアーがコードの構成を捉えやすい
  • 設計全体を俯瞰できるので、局所最適な設計変更を回避できる

取り組みを経て

SWQAと開発サイドがコミュニケーションするためのツールが増えたことで、より本質的な評価をすることができるようになりました。 開発上流から関わることができ、少しはWモデルに近づいた気がします。

また、メンバーからもシフトレフトというワードがでるようになったり、何も言わなくてもソースコードと設計ドキュメント変更のPullRequestが上がってきたり良い傾向。 イケてるドキュメントが増えると、新たに作成する際のお手本も増えて書き始めるハードルが下がるはず。

旅はまだまだ続きます。

株式会社フォトシンスでは、一緒にプロダクトを成長させる様々なレイヤのエンジニアを募集しています。 photosynth.co.jp

Akerunにご興味のある方はこちらから akerun.com