技術記事を書く人に使ってほしい！「検証環境」の記述を楽にするスクリプトを作りました

検証環境が記載されている技術記事は再現性が高い

現代、技術記事は日々ものすごい数が公開されています。技術情報やノウハウがいつでもどこでも読める時代、技術者としてはとってもありがたいですよね。

世の中にここまで技術記事が多くなると、質の良い記事もあれば質の悪い記事もあります。その質を大きく左右するのが再現性の高さだと思います。

例えば「記事を参考にやってみたけど、全然うまくいかない！」なんていう経験、ありませんか？良さそうな技術情報でも、自分の環境で再現できなければ意味がありません。

再現性の高い記事を書くために、非常に重要なのが検証環境の情報です。検証環境が書かれていると、読者が自分のとの環境を照らし合わせることができるため、うまくいかなかったときのトラブルシューティングができます。

検証環境を毎回書くのも大変ですので、軽くスクリプト化してみました。

検証環境

本記事にも、もちろん検証環境を記載しておきます。

• macOS Sierra 10.12.3
• AWS CLI 1.11.68
• Python 2.7.11

書いてみた

弊社では AWS に関する技術記事が多いので AWS CLI を用いた技術記事の検証環境を作ることを題材としてみました。

まずは適当なディレクトリに、以下のシェルスクリプトファイルを配置します。ここでは 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 を題材に取り上げましたが、他の言語やツールでも活かせると思います。本記事を参考に、ご自身の「検証環境」を生成するシェルスクリプトを作ってみてください。

参考

• Mac OS Xのバージョンをシェルスクリプトで判定 - Qiita
• [Linux][sed] 文字列から部分抽出する方法 - Qiita