はじめに
突然ですが、皆さんは「画面仕様書」というものをご存知でしょうか。
読んで字の如く「画面」の「仕様書」なんですが、具体的には以下のような内容が記された資料のことを指します。
- プログラムの設計図となるもの
- 各画面のデザイン・動作・機能・画面遷移などを記述する
プログラムの実装をする前に作っておくことで、画面内のルールを統一させたりサイト全体の構成を最適化できたり、
領域の異なるエンジニア（BEとFEなど）同士のコミュニケーションにも役立つ素晴らしいドキュメントです。
さて、そんな素敵なドキュメントですが、しっかり使えるものを作ろうとするとそれなりに手間のかかる代物でもあります。
画面ごとにデザイン画像を貼り付けて、パスや画面遷移をまとめて、リクエストがどうでレスポンスがこうで……
というのを全画面作らないといけないんです。ほぼ手作業で。
大変だし、時間がかかるし、同じ作業ばっかりで飽きてしまう！！！
特にエンジニアの方は、こういった同じことを繰り返す系の作業は苦手な方が多いんじゃないでしょうか（僕の偏見だったらごめんなさい）
かくいう僕も、画面仕様書を苦しみながら手作業で作っていたエンジニアです。
全部自動で生成してくれとは言わない。
せめて、パスごとのリクエストとレスポンスだけでもいい感じにドキュメント化してほしい。
そんな思いがきっかけで、PHPファイルから自動でドキュメントを生成するツールを作ろうと心に決めたわけなのです。
全ては僕が楽をするために。
作りたいもの
これまでスプレッドシートで作っていた画面仕様書を参考に、生成したいドキュメントのサンプルを作成しました。
ざっくり以下の５項目がわかるようなものにしたい、といった感じです。
- 画面名
- 画面のURL
- 動作パターン（「ログインユーザーごと」と書いたが、ここは自由に決められる形にしたい）
- FEとBEでやり取りするデータ
- 画面キャプチャ
ただ、これらの項目を全て自動で生成するのは難しいと思っています。
特に画面キャプチャなんかは、機能としての実装は可能だと思いますが、プロジェクトディレクトリの中に
わざわざキャプチャ画像なんかを入れておく必要が出てくることになるため、現実的じゃないです。
よって、他の４項目を自動生成し、そこに画面キャプチャを手動で追加できるような仕組みが作れたらいいのかなと考えています。
これからの作業
さて、作りたいものも何となく想像できたところで、これから具体的にどんな作業をしていくのか考えていきます。
まずは、既存のPHPファイルからドキュメントを生成するツールを調査してみたいですね。
既存のツールがどういう仕様で、どんな技術を使って、どういったドキュメントを作成しているのかを調査し、
僕が作りたいツールに活かせそうな部分を参考にさせていただきたいところです。
また、実際にツールをデモしてみて、より詳しく中身がどうなっているのかも調べていきたいです。
調査が終わったら、本格的に仕様を決めていこうと思います。
大枠は先ほどのサンプルに従う形にしたいですが、調査結果を受けて改善できるポイントがあればどんどん変えていきたいです。
仕様が固まったら、早速開発に取り掛かるつもりです！
７月中に仕様を決め切りたいところ。
また、これらの作業は、全てこのブログに記事として投稿していく予定です。
隔週更新を目標に作業を進めますが、進捗によって遅れたり早まったりはすると思います。
というかします。絶対。
最後に
今回は、僕がPHPファイルからドキュメントを生成するツールを作ろうと思った経緯と、今後の作業計画についてお話ししました。
次回から調査結果をまとめるフェーズに移っていきます。
更新されたらぜひそちらも読んでいただけると嬉しいです。
