この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
検証環境が記載されている技術記事は再現性が高い
現代、技術記事は日々ものすごい数が公開されています。技術情報やノウハウがいつでもどこでも読める時代、技術者としてはとってもありがたいですよね。
世の中にここまで技術記事が多くなると、質の良い記事もあれば質の悪い記事もあります。その質を大きく左右するのが再現性の高さだと思います。
例えば「記事を参考にやってみたけど、全然うまくいかない!」なんていう経験、ありませんか?良さそうな技術情報でも、自分の環境で再現できなければ意味がありません。
再現性の高い記事を書くために、非常に重要なのが検証環境の情報です。検証環境が書かれていると、読者が自分のとの環境を照らし合わせることができるため、うまくいかなかったときのトラブルシューティングができます。
検証環境を毎回書くのも大変ですので、軽くスクリプト化してみました。
検証環境
本記事にも、もちろん検証環境を記載しておきます。
- macOS Sierra 10.12.3
- AWS CLI 1.11.68
- Python 2.7.11
書いてみた
弊社では AWS に関する技術記事が多いので AWS CLI を用いた技術記事の検証環境を作ることを題材としてみました。
まずは適当なディレクトリに、以下のシェルスクリプトファイルを配置します。ここでは copy-env.sh
というファイル名にします。
copy-env.sh
#!/bin/bash
set -eu
# macOS のバージョン情報を出力
function show_ver_name () {
VER_NUM=`echo $1 | awk -F. '{ print $1 "." $2 }'`
case $VER_NUM in
"10.8")
echo "Mountain Lion"
;;
"10.9")
echo "Mavericks"
;;
"10.10")
echo "Yosemite"
;;
"10.11")
echo "El Capitan"
;;
"10.12")
echo "Sierra"
;;
esac
}
OS_VER=$(sw_vers -productVersion)
OS_VER_NAME=$(show_ver_name $OS_VER)
# AWS CLI のバージョンを出力
AWS_CLI_VER=`echo $(aws --version 2>&1) | sed 's/aws-cli\/\(.*\)Python.*/\1/'`
# Python のバージョンを出力
PYTHON_VER=`echo $(python --version 2>&1)`
# MarkDown 形式で出力
{
echo "## 検証環境"
echo ""
echo "- macOS $OS_VER_NAME $OS_VER"
echo "- AWS CLI $AWS_CLI_VER"
echo "- $PYTHON_VER"
} | pbcopy
あとはこのファイルの実行権限を与え、実行します。すると、クリップボードに検証環境のテキストがコピーされます。あとは好きな場所に貼り付けてください。
$ chmod +x copy-env.sh
$ ./copy-env.sh
## 検証環境
- macOS Sierra 10.12.3
- AWS CLI 1.11.68
- Python 2.7.11
まとめ
本記事では AWS CLI を題材に取り上げましたが、他の言語やツールでも活かせると思います。本記事を参考に、ご自身の「検証環境」を生成するシェルスクリプトを作ってみてください。