ドキュメントのテンプレをすぐにコピペできるようにしておくシェルスクリプト


背景

  • システム開発をする上で、ドキュメントの形式を適切に揃え、管理することは重要。
  • テンプレが整理されておらず、各々フリーフォーマットで書き始めると後から見たときに非常に見づらいドキュメントになってしまい、結果として誰も読めなくなり、読まなくなる
  • それゆえに、システム開発の現場では大体、「Githubでコードレビューする場合のテンプレはこれ」「メールで客先に連絡する場合のテンプレはこれ」「Backlogにあげるリファクタリングチケット用のテンプレはこれ」というふうにテンプレが決まっている。

問題

  • バグ管理システム、チケット管理システム、タスク管理システム、github、メール…でテンプレの在り処が統一されてなくて非常にめんどくさい
  • 殆どのこういった情報まとめ系システムには標準のテンプレート機能があったりするが、システムごとにインタフェースが各々微妙に違ったりする。手順を忘れてめんどくさい。
  • テンプレートが記述してあるページをブラウザのお気に入りに入れる運用で対応するけどやっぱりめんどくさい

解決案

  • コマンドラインから一発で、かつ統一的なインタフェースでテンプレートを呼び出せるようにする

手順概要

  1. テンプレをテキストファイルとして保管しておく
  2. テンプレをコピペするシェルスクリプトを書く
  3. 実行権限振る
  4. パスを通す

テンプレをテキストファイルとして保管しておく

* 例えば、`~/work-tmpl/`以下にテンプレートテキストを置きます。ついでに次の項目で説明するシェルスクリプト`tmpl`もここに配置します。

cd
mkdir work-tmpl
cd work-tmpl
vi bug

試しに、「不具合報告用テンプレート」として、「bug」というテキストファイルを作成します。

# 概要
* この不具合に対する概要を記述

# 発生ブラウザ
* IE8

# 発生環境
* ステージング環境

# 前提条件
* この不具合が再現する条件を記述

# 再現方法
1. hogehogeする
2. fugafugaする
3. foofooする

テンプレをコピペするシェルスクリプトを書いておく

今回はシェルスクリプトのファイル名を`tmpl`にしておきます。
タイプ数が短い名前にしておくほうがいざ呼ぶときに楽ちんですが、他のスクリプトと被らない・自分が名前を忘れない程度にしておきましょう。

#!/bin/sh
tmpl_path=~/work-tmpl
cat ${tmpl_path}/${1} | pbcopy
echo 'copied!'

実行権限振る

chmod 755 tmpl

パスを通す

* 実際に使うときに一々テンプレートのあるフォルダに移動するなんてやってらんないのでパス通してどこからでもこのスクリプトを呼べるようにしておきます。
* .bash_profileに以下を追記

PATH=$PATH:~/work-tmpl

# 実行

tmpl bug

クリップボードに、先程作成したテンプレートがコピーされています。

後はメールに貼り付けるなりJIRAに貼り付けるなりRedmineに貼り付けるなりして自由に編集しましょう。

最後に

開発系のお仕事じゃなくても例えば日報とかでも使えます。