今週やったこと
ドキュメント作成
自分が実装した処理の引き継ぎや、これから実装するAPIレビューなどを行いやすくするために必要と思えるドキュメントを作成しました。
以前はドキュメントはテキストで書くことが多かったですが、リモートでやり取りを行う上ではテキストと口頭での説明だけだと自分も上手く伝えられないし相手にも負荷を与えてしまう場面がよくありました。
それを踏まえて、今回はAPIの設計レビューでは作画ツールで処理フロー図を用意したり、ローカル環境の構築手順を説明するドキュメントでは実際に自分のローカルでDockerコンテナを起動する様子を動作に収録して貼り付けてみました。
これらを用意することで相手にとって新しい情報でも直感的に理解しやすくなった手応えはありました。
ただ、動画などは仕様変更の際にメンテナンスできるものではないので、一時的な情報として割り切る必要はあるように思いました。
目的としては「自分が伝えたい情報を相手に効率よく理解してもらう」ことなので、手段は場面に応じて最適なものを選択するように心がけていきたいです。
少なくとも試してみないとメリットとデメリットが見えてこないので、今後もいろいろアイデアを試してみたいと思います。
API設計
画面上で選択した複数のレコードを一括で削除したい要件があり、APIのHTTPメソッドとしてはDELETEが自然だと思いますがDELETEにリクエストボディを持たせることは一般的に推奨されていないようなので設計時点でいろいろ調査しました。
改めて調べてもやっぱりDELETEはボディを持たせない方が良さそうという結論になったため、以下の二つのAPIを実装することにしました。
- POSTメソッドで削除対象のレコードのIDをボディに持たせて、RedisにIDを保存し、Redisのキーを返り値にするAPI
- DELETEメソッドでRedisのキーをパラメータに持ち、Redisから削除対象のレコードのIDを取得してから、一括でレコードを削除するAPI
方法としてはPOSTメソッドでそのままAPIの処理内で削除を行うこともできますが、全体の処理の読み取りにくさに繋がると考え上記のようにしました。
今週学んだこと
ドキュメントの書き方について調べた
これまでの仕事の中で定期的にドキュメントの書き方については調べていますが、今月もドキュメントを書くことが多かったので再度自分の知識をアップデートするためにいろいろ記事を読みました。
こちらの記事の以下の部分が印象的でした。
GitHub / ドキュメント用リポジトリ
このリポジトリは可能な限り簡単に更新できることが理想なので、レビューは不要としています。書き手が変更の PR (Pull request) を作成し、 main へマージすると変更内容が Slack に通知されるので、間違った変更が行われた場合や、最新の情報を他のメンバーも把握することができます。
ドキュメント作成などはCopilotが活用しやすい分野だと思うので、リポジトリ内にドキュメントを書くことまでは自分も考えていたのですが、ドキュメント用のリポジトリを作成してそこをレビュー不要にするということは思いついていませんでした。
確かにドキュメントは毎回レビューしているとメンバーの負荷が高くなる可能性が高そうなので、mainにマージされた後でも気づいた時に修正する形で良いと思いました。
プロダクトコードと違い、mainに正しくない内容が含まれたとしても即時に問題が起きるわけではないし、バージョン管理されているので前のバージョンに直しやすいし、マージ後にSlack通知が飛べば変更された内容もすぐ気づけて運用しやすそうに感じます。
勉強になった記事など
ChatGPTを活用した業務マニュアル作成について
マニュアル作成はAIが得意とする作業だと思うので、なるべくChatGPTやCopilotがマニュアル作成できる形でデータを集約できると良さそうに思いました。
最終的なレビューを開発メンバーが行なって、ドラフトまではAIで作成できると生産性が上がりそうです。
ただ、AIが学習しやすくするためのデータの集め方やセキュリティ面で問題が無いようにするための進め方など、実際に導入するにはクリアしないといけないことが多いはずなので、まずは自分のプライベートの学習などで少しずつ試してみたいと思います。
