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

ツール

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

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

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

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

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

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

検証環境

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

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

参考

AWS Cloud Roadshow 2017 福岡

  • Masataka Higashijima

    毎回検証環境をコマンド打つってちょっとした操作だけど確かに面倒です
    うちはLinuxなのでほとんど同じように使えそうなので活用させていただきます

    • suwa.yuki

      > Masataka Higashijima さん
      コメントいただきありがとうございます!
      ぜひ、ご自身でよく書かれる技術記事に使う技術(言語など)用にカスタマイズして使ってみてください。

      • Masataka Higashijima

        こちらに記事をかかせていただきました書かせていただきました
        http://boctoc1969.hatenablog.com/entry/2017/04/11/001100
        そのまま丸写しでは意味がないのでちょい足ししてみたので、よろしかったら見てください

        • suwa.yuki

          > Masataka Higashijima さん
          拝見いたしました。
          テーブル表示も技術記事でよく見かけますよね。
          見やすくまとめられるので、スクリプト化は大変有用だと思います。
          参考にさせていただきます。ありがとうございます!