小型ツールを同僚へ渡すときは、コードの説明より先に、何を入れて、何が出れば成功かを伝えます。作った人が隣にいなくても、使う人が対象と結果を確かめられる説明メモを用意します。
例として、在庫一覧の不備を点検する架空のツールを考えます。元の表を直接直さず、受付ID、数量、状態の不備を確認用一覧へ出す用途です。以下の名前や入力値は記入例で、実在する業務システムの仕様ではありません。
用途と対象の説明
冒頭は誰のどの作業を助けるものかを書きます。「在庫ツール」だけでは、残数を変更するのか、誤りを見つけるだけなのかが分かりません。
用途: 在庫一覧の入力不備を確認する。
入力: 確認用シートの受付ID・数量・状態。
出力: 不備のある行と確認理由の一覧。
操作する人: 入力を点検する担当者。
結果を判断する人: 元の在庫資料を確認できる担当者。
この例で変更する場所: 確認用の出力だけ。元の在庫値は変更しない。
何を変更するかを具体的に示すと、実行してよい対象を選べます。業務の対象外も入力の種類や使う場面で説明してください。
準備と起動の手順
入力するファイルやシートの場所、必要なアカウント、初回の承認を記載します。GASを使うなら、Googleサービスの承認で必要な権限と、実行する人を確認します。
手順は「設定する」「実行する」だけで終わらせず、どの画面から、どの関数やメニューを選ぶかを書きます。関数名は実際のツールと一致させます。説明の例の名前を、そのまま存在する機能のように案内しないことが大切です。
設定の値に秘密が含まれる場合は、設定名と登録先だけを書きます。APIキーや認証情報の入った画面を、説明画像としてそのまま貼る必要はありません。
成功と不備を比べる見本
小さな入力見本と、期待する出力をそろえます。例なら「受付IDがあり、数量が0、状態が未処理」の行は正常です。空欄や重複がある行は、対象行と理由が一覧へ出ることを確認します。
| 入力の例 | 期待する結果 |
|---|---|
| A001・0・未処理 | 不備の一覧へ出ない |
| 受付IDが空欄 | IDの不足として報告 |
| 数量が空欄 | 数量の確認が必要と報告 |
| 同じ受付IDが2件 | 重複を報告 |
成功の見本だけでは、入力を間違えたときの動きが分かりません。利用者が安全に試せる架空のデータを添え、実データで確認する前に見比べられる形にします。
失敗したときの止め方
エラーが出たら、実行した時刻、入力、表示されたメッセージ、最後に確認できた出力を控える手順を書きます。GASなら実行ログの確認先も案内します。
同じボタンを何度も押す前に、保存や通知が既に終わっていないかを確認します。再実行してよい条件と、担当者へ連絡する条件を分けてください。問い合わせ先も作成者個人の記憶に頼らず、担当者と代わりの確認先を残します。
共有後の保守
説明メモには更新日、対象バージョン、変更した点を記録します。入力列を増やしたなら、コードだけでなく入力見本と成功例も直します。
最初の引き継ぎでは、受け取った人がメモを読んで練習用データを処理し、分からなかった箇所を記録してもらいます。作成者が口頭で補足した内容もメモへ戻せば、次の担当者へ同じ説明を繰り返さずに済みます。この記事では、実際の社内配布やツールの実行は行っていません。
小さな題材を選ぶ際はPythonで作れる業務用の道具、処理を読みやすく分ける方法はGASコードの分割も参考になります。
