社内Wikiに情報を書くときに守ってほしい、たったひとつのルール

このページについて

これは、社内 Wiki に情報を書くときに、私が個人的に守っていて、チームメンバにもできるだけ守ってほしいルールの紹介記事です。このルールを実際に運用するためのコツについても、基本ルールの派生という形で紹介します。

想定する環境

この記事は、社内に Wiki があって、フォーマットが決まったドキュメント（仕様書や手順書など）とは別に、各人がメモを自由に書いて共有できるような環境を想定しています。

Wiki の種類は問いません。PukiWiki、MediaWiki、Confluence、Esa、Redmine などのプロジェクト管理ツール付属の Wiki などなど……何でもいいです。Word 文書などにも適用できなくはないですが、文書を気軽に分けるのが難しい場面には、あまり向かないかと思います。

ルール：「このページについて」という欄をページの先頭に用意し、そのページの概要を1〜2文で書く

守ってほしいルールはこれだけです。単純ですが強力で、きちんと守ろうとすると意外と面倒なルールでもあります。

例えば、何かのインストール作業をメモしておきたい場合、「このページについて」欄には以下のような文章を書きます。

## このページについて

これは、システムAの開発環境を構築するために、Windows 7 にソフトウェアBをインストールした際のメモです。

## 手順

（これ以降に、実際に実行した手順のメモ）

または、何か新機能の実装をしたくて、事前に設計を検討した場合は、こんな感じで書きます。

## このページについて

これは、機能Cの設計についてチーム内で議論するために、個人的に作成した設計案です。設計の事前知識として、既存のソースコードを調査した結果も含めています。

## 設計案

（これ以降に設計案とソースコードの解説）

Wikipedia の記事は、よく「〜とは、…である。」という一文から始まりますが、それをイメージしてもらえると分かりやすいかもしれません。

同じような内容がページの先頭に書いてあれば、この欄の名前は「このページについて」にしなくても、「概要」でも "About this page" でもなんでも良いです。

このルールの目的

このルールを徹底する目的は、そのページを開いた人に 「このページに、自分がいま知りたい情報が書かれているか？」を瞬時に判断する ための情報を与えることです。

社内 Wiki を実際に使っている人なら、このページにはこんなことが書いてあるだろうなーと思って読み始めたら、実際は全然違うことが書かれていた、という経験が何度もあると思います。例えば、こんな感じです。

• インストール手順書かと思って読んでいたら、インストール時に試したことを適当な順序で書いてあるだけのメモだった。書いてある手順を上から順に実行したところ、途中で失敗してしまった。で、メモにも「このコマンドは失敗した」とか書いてある。
• ある機能の設計に関するメモかと思ったら、単なる設計案の一つだった。最終的に実装されたソースコードの設計とは全く一致していなかった。

誤解を避けるために強調しておくと、私は、中途半端なメモを Wiki に書かないで欲しい、とか、そういう中途半端なメモは消して欲しい、とか言いたいわけではありません。

ただ、そのページがどういう状態なのかが明示されていないと、

あるページAを、ここには正確な情報が書いてある、と思って読み始める
↓
期待を裏切られる
↓
別のページBを、ここには正確な情報が書いてある、と思って読み始める
↓
期待を裏切られる
↓
この Wiki に書いてある情報はどれも信用できない！ となって Wiki を読まなくなる

という悪循環を起こしかねません。そうなると他の人がいくら Wiki に有効な情報を書いていっても、その情報は読まれない、というもったいないことになってしまいます。

ページの先頭にただのメモだと明示してあれば、読み手が 「他に有力な情報源が見当たらないので、これを頑張って読み解こう」 と判断することも十分ありえますし、結果として必要な情報が書いてなくても、期待を大きく裏切ることにはなりません。Wiki 全体でそういう状態を保ち、モラルハザードを防ぐ……というのがこのルールの目的です。

以下は、このルールを実際に運用するために守ったほうがよい、このルールの派生系です。

派生(1)：ページを更新し終わったタイミングで「このページについて」の内容を見直す

ページの内容を色々書いているうちに、最初に書こうと思っていた内容とはズレていってしまう、ということはよくあると思います。理想的には、内容がズレた時点で直したほうがよいのですが、少なくともページを更新し終わったタイミングでは必ず直すようにしましょう。

例えば、設計案を色々書いていたつもりが、最終的な設計についてもそのページに書いてしまい、他のページにはそこまで詳しい情報がまだ書かれてない、という状態になったとします。

もちろん最終的な設計のページをきちんと用意したほうが良いですが、「このページについて」欄を以下のように直すだけでも、後から読む人にとっては役立ちます。

## このページについて

これは、機能Cの設計についてチーム内で議論するために、個人的に作成した設計案です。最終的に採用したのは案3で、このページに書いてある案3の詳細は、最終的な設計と同じです。

派生(2)：「このページについて」から外れる内容が増えてきたら、別のページに分ける

書いているうちに「このページについて」には書いてない内容が増えてきた、あるいは内容に合わせて「このページについて」を直したら1〜2行では収まらなくなった、という場合にはページを分けましょう。

例えば、あるシステムAの開発環境構築手順書を作っているうちに、内容が膨らんできて、「このページについて」欄が、

## このページについて

これは、システムAの開発環境を構築するための手順書です。このシステムのサブシステムB、C、Dの知識がないと、この手順は意味不明に見えるかもしれません。そのため、このシステムのサブシステムB、C、Dの関係についても、構築手順書の途中で説明します。

のようになったら、恐らくそのサブシステムB、C、Dの解説は別のページに分けたほうがいいでしょう。そして、以下のようにリンクを書くだけにするのが無難です。

## このページについて

これは、システムAの開発環境を構築するための手順書です。これらの手順が何をしているか理解するためには、このシステムAの構成に関する知識が必要です。システムAのサブシステムについての知識がない場合は、必ず先に [サブシステムの解説](http://wiki.example.com/subsystem) を読んでください。

そうしないと、読み手が、1個の長いページのなかで、自分の知りたい情報を探しまわる羽目になってしまいます。

別のページに分けたら読まれないかも？と思うかもしれませんが、そういう人は、同じページ内に書いてあってもどうせ読みません。それなら、読む気のある人向けに、少しでもわかりやすくしたほうが良いです。

派生(3)：他の人が書いた「このページについて」も直していい

他の人が書いたページでも、「このページについて」に書かれた内容と、本文が違っていたら、積極的に直しましょう。また、そもそも「このページについて」欄が無かったら追加しましょう。

基本ルールに書いた通り、目的は Wiki 全体の利用価値向上、モラルハザード防止です。そのためには、内容は直さずに、「このページについて」欄を直すだけでも十分意味があります。

例えば、あるページを読んで、その内容が間違っていた場合、私だったらこういう文章をページの冒頭に書いて、内容は修正も削除もせずに残しておきます。

## このページについて

私（吉澤）が 2016-04-25 に調べた範囲では、このページに書かれた設計は、現在の実装と違っているようです。そのため、設計情報としては参考にしないことを推奨します。

ただ、当時の設計思想など、何かの参考になる可能性を否定しきれないため、削除せずに残しておきます。

派生(4)：本文は頑張らない

Wiki に書かれた情報の品質は高ければ高いほど良いですが、敷居が上がって、Wiki に書くのが一人か二人だけ、になってしまうのも困ります。そのため、「このページについて」欄以外のルールはあまり多くしないほうが良いでしょう。

また、一般的な話として、「他人のために細かく書いてあげている」というつもりで書いていると、読んでもらえなかったときの心理的ダメージが大きいです。そのため、手間のかかる本文の品質は、自分が後で読んで困らない程度にしておくことをお勧めします。

まとめ

今回は、普段はあまり書かないタイプの、仕事のノウハウについての記事でした。

私は自他共に認めるメモ魔で、やたらあちこちにメモを書き散らしています。そうやって書き溜めているメモがたまに同僚から「役立った」と言ってもらえることもあるのですが、それと同時に「自分はそこまでできないし、やらない」という反応をされることが多かったりします。

書く分量が少なくても、少しの工夫で、後から読んで役立つような文章を書くことはできるはずなんだけどなあ……と思い、自分なりに本質的と考える部分をまとめてみました。Wiki も普及してだいぶ経つので、今更感のある話題ではありますが、他の人のノウハウも色々伺ってみたいところです。

Swim.com の workout データをエクスポートする方法

Swim.com 活用のすすめ

自分以外に使っている人を見たことないですが、Swim.com というスイマー用の SNS があります。

この SNS は、泳いだ距離や速さを自動的に記録できるスイムウォッチや、Swim.com アプリが動くスマートウォッチに対応しており、スイマー同士でスコアを競えるようになってます（参考：Swim.com に対応したスイムウォッチ一覧）。まあ、SNS ですけど、自分のデータをアップロードして、確認するためだけにも使えます。

僕は、去年の9月までは Pebble Time で水泳データを記録していたのですが、10月以降はより高機能な Garmin Swim というスイムウォッチに乗り換えました。Garmin Swim のデータは Garmin Connect というサイトで確認できるのですが、以前のタイムとも比較したいので、Garmin Connect のデータを Swim.com にも連携させています。

図にすると、以下のような感じです。

このように連携させることで、以下の Workout 画面（https://www.swim.com/my-workouts/）で、Pebble Time の測定値と Garmin Swim の測定値を一覧できます。

今回の目的

Swim.com で一覧表示はできるんですが、1回あたりに泳いだ距離や、泳ぐペースの変化をグラフ表示するような機能はありません。また、Garmin Connect には CSV エクスポート機能があるのですが、Swim.com の方には CSV エクスポート機能も API もなんにもありません。厳しい……。

異なるスイムウォッチで測定した結果をなんとかグラフ化したいと思い、Workout 画面のデータをエクスポートする処理を実装しました。

採用した方法：JSON を手作業でテキストファイルに貼り付けて、Ruby のスクリプトで CSV に変換

色々試したのですが、Swim.com はログイン機能が特殊で、単にユーザ名とパスワードを POST するだけではログインできそうになかったので、自動化は早々に諦めました。厳しい……。

その一方で、一度ログインしてしまえば、Workout 画面の情報は GET で簡単に取得できることがわかりました。Workout 画面は最新の10件のデータを表示し、ページの末尾に到達すると次の10件を読み込むのですが、内部的には以下の URL に GET でアクセスしていました。

https://www.swim.com/workout/listing/search?pageIndex=1&pageSize=10&orderBy=workoutdate&orderDir=DESC&_=1461254054552

ざっと試した感じでは、この pageSize を 10 から 1000 に変えれば 1000 件取得できるし、orderDir を DESC から ASC に変えれば昇順に取得できるみたいです。やさしい……。

というわけで、こんな手順でエクスポートすることにしました。

1. Web ブラウザで Swim.com にログインする
2. Web ブラウザで https://www.swim.com/workout/listing/search?pageIndex=1&pageSize=1000&orderBy=workoutdate&orderDir=ASC にアクセスする
3. 2 で表示された JSON を swim_com.json にコピペする
4. swim_com.json と同じディレクトリに swim_com_parser.rb を置いて、ruby swim_com_parser.rb を実行する
5. パース結果が swim_com.csv に出力されるので、このファイルをよしなにする

swim_com_parser.rb は Gist で公開しておきました。ご参考ください。

JSON Parser for swim.com workout data

関連記事

qiita.com

Ansible でインベントリのホスト変数を when に渡した際の不思議な動作（Ansible 1.9/2.0 共通）

Ansible を使っていて、不思議な動作に遭遇したので深入りしてみました。

今回の落とし穴

同じグループに属するホストのうち、特定のホストのみで実行したいタスクがある、ということがたまにあります。そういうとき、私はインベントリファイルでホスト変数を定義して、この変数で処理を分岐させる、ということをしていました。

例えば、Webserversグループのうち、Webサーバ1番のみで実行したいタスクがある場合、インベントリファイルを以下のように書きます。

[webservers]
web1.example.com var1=true
web2.example.com var1=false

そして、以下のように when ステートメントを使えば、web1 のみでコマンドが実行されます。

- command: /usr/bin/do_something.sh
  when: var1

しかし、ホストの追加時に変数 var1 の定義をさぼってしまうと、実行時に「var1 が未定義である」というエラーが発生し、playbook の実行が止まってしまいます。

[webservers]
web1.example.com var1=true
web2.example.com var1=false
web3.example.com

それならタスクの方で var1 の中身を調べる前に、var1 が定義済みかどうかを調べればよいのでは？と思い、タスクを以下のように書きなおしてみました。

- command: /usr/bin/do_something.sh
  when: var1 is defined and var1

しかし、これを実行すると、web1（var1=true）だけでなくて web2（var1=false）でもこのコマンドが実行される という問題が発生しました。えっ……？ どういうこと？！

この問題の原因っぽい（でも原因の説明にならない）もの

この問題の原因っぽいものとして、「インベントリファイルの中で定義した変数は、すべて string として解釈される」という Ansible の仕様があります。

Values passed in using the key=value syntax are interpreted as strings. Use the JSON format if you need to pass in anything that shouldn’t be a string (Booleans, integers, floats, lists etc).
Variables — Ansible Documentation

しかし、これは when: var1 と書いた場合と when: var1 is defined and var1 と書いた場合で結果が違ってしまうことの説明にはなりません。

いろいろなパターンを試す

こうなってくると when 自体どこまで信用していいのか不安になってきたので、いろいろなパターンで動作検証してみました。また、Ansible 1 系から 2 系へのアップグレード中にこの問題に遭遇したため、Ansible 1.9.4 と 2.0.1 の両方で検証しました。

動作検証の方法

3種類のインベントリファイルを用意しました。違いは、変数 var1 のみです。

inventory_true

localhost var1=true

inventory_false

localhost var1=false

inventory_null

localhost var1=

これらのインベントリファイルを使って、色々な when ステートメントを記載した playbook を実行しました。タスクの詳細は↓をご覧ください。

ansible-2.0-sample/main.yml at master · muziyoshiz/ansible-2.0-sample

動作検証の結果

Ansible 1.9.4 と 2.0.1 の両方で、ほとんど同じ結果になりました。ただし、var1= と書いた場合は、Ansible 1.9.4 だと when: var1 の場合に限り、fatal エラーが出て異常終了しました。

when statement	var1=true (1.9/2.0)	var1=false (1.9/2.0)	var1= (1.9)	var1= (2.0)
when: var1 is defined	ok	ok	ok	ok
when: var1	ok	skipping	fatal	skipping
when: "{{ var1 | bool }}"	ok	skipping	skipping	skipping
when: var1 == true	skipping	skipping	skipping	skipping
when: var1 == "true"	ok	skipping	skipping	skipping
when: var1 == false	skipping	skipping	skipping	skipping
when: var1 == "false"	skipping	ok	skipping	skipping
when: var1 is defined and var1	ok	ok	skipping	skipping
when: var1 is defined and {{ var1 | bool }}	ok	skipping	skipping	skipping
when: var1 is defined and var1 == true	skipping	skipping	skipping	skipping
when: var1 is defined and var1 == "true"	ok	skipping	skipping	skipping
when: var1 is defined and var1 == false	skipping	skipping	skipping	skipping
when: var1 is defined and var1 == "false"	skipping	ok	skipping	skipping

この結果をざっくりまとめると、以下のようになります。

• when: var1 と書いた場合は、var1 が文字列 "true" なら true、"false" なら false と解釈される。これは、普通の人が期待しそうな動作（と思う）。
• when: var1 is defined and var1 と書いた場合は、var1 に文字列が何かしら設定されていれば、それが "true" でも "false" でも true と判定してしまう。
• この奇妙な動作は、Ansible 2.0 へのバージョンアップが原因ではない。
• {{ var1 | bool }} と boolean への変換を明示すれば、期待通りに動作する。
• var1 を文字列 "true", "false" と比較すれば、期待通りに動作する。
• その一方、var1 と、boolean 型の true, false との比較は、常に false になる。

true/false を True/False に変えた場合の動作（2016-04-01追記）

この件について GitHub で issue として報告してみたところ、true じゃなくて True（先頭が大文字）と書け、という返信をもらいました。

Inconsistent behavior of when statement · Issue #15218 · ansible/ansible

そこで、

inventory_large_true

localhost var1=True

inventory_large_false

localhost var1=False

を新たに用意して、改めて動作確認してみた結果はこちら。動作に一貫性がなさそうに見える箇所に (inconsistent) と書いています。

when statement	var1=true	var1=false	var1=True	var1=False
when: var1 is defined	ok	ok	ok	ok
when: var1	ok	skipping (inconsistent)	ok	skipping
when: var1 | bool	ok	skipping	ok	skipping
when: var1 == "true"	ok	skipping	skipping	skipping
when: var1 == "True"	skipping	skipping	skipping	skipping
when: var1 == "false"	skipping	ok	skipping	skipping
when: var1 == "False"	skipping	skipping	skipping	skipping
when: var1 is defined and var1	ok	ok (inconsistent)	ok	skipping
when: var1 is defined and var1 | bool	ok	skipping	ok	skipping
when: var1 is defined and var1 == "true"	ok	skipping	skipping	skipping
when: var1 is defined and var1 == "True"	skipping	skipping	skipping	skipping
when: var1 is defined and var1 == false	skipping	skipping	skipping	ok
when: var1 is defined and var1 == "false"	skipping	ok	skipping	skipping
when: var1 is defined and var1 == "False"	skipping	skipping	skipping	skipping

この結果を見る限り、ホスト変数として True/False と書くと boolean として解釈されるようです。また、文字列としての "True"/"False" とは一致しなくなりました。

こうなると、ホスト変数に true/false と書いた場合に、どうして when: var1 だけは変数を boolean として扱ってくれる（扱ってしまう）のか気になってきます。中途半端に型の概念が導入されていて、個人的にはなんだか気持ち悪くなってきました……。

結論：特定のホストのみで実行したいタスクがある場合、結局どうすればいいのか（2016-04-01修正）

インベントリファイルでホスト変数を定義するときに、True/False の先頭を大文字にしないと正しく動作しない こともある と認識した上で、playbook を以下のように書くのが良さそうです。

inventory

host1 var1=True
host2
host3

playbook

- command: /usr/bin/do_something.sh
  when: var1 is defined and var1

ただ、処理を分岐させたい場所すべてで、var1 is defined and という冗長な記載が必要になってしまうのが、嫌なところです。かといって、この記載をサボると、var1 の定義がないホスト（上記の host2, host3）で異常終了してしまいます。

代案としては、記載を簡潔にするために、変数定義の有無だけをフラグとして使う方法も考えられます。つまり、インベントリファイルには host1 var1=True と書くものの、playbook には

- command: /usr/bin/do_something.sh
  when: var1 is defined

と書いて、変数 var1 の中身は検査しないという方法です。ただ、この方法は、事情を知らない人には「var1=False と修正すれば動作を変更できる」と誤解される危険性があります。なかなか悩ましいところです……。

Ansible 2.0 で追加されたモジュールおよびオプション一覧を無理矢理作る

Ansible 2.0 の売りの一つ：新モジュールの豊富さ

Ansible 2.0 Has Arrived（日本語訳：Ansible 2.0リリース！）のなかで、Ansible 2.0 は「200個以上の新モジュール」を同梱している、と謳われています。

Ansible 2.0 also continues our long “batteries included” tradition by including over 200 new modules. Ansible 2.0 Has Arrived

モジュールの一覧は All Modules (Ansible Documentation) にあります。個々のモジュールのページを開くと "New in version 2.0." などと書いてあるのですが、2.0 で追加されたモジュールの一覧は存在しないようです。

しかし、Ansible 2.0 に移行したら、せっかくだから 2.0 でしか使えないモジュールやらオプションを使ってみたいものです。そこで、このページをクロールして、Ansible 2.0 で追加されたモジュールとオプションを列挙してみました。

今回実装したクローラ

Ruby のライブラリ Anemone を使ったクローラを書きました。良い機会なので「Rubyによるクローラー開発技法」を一通り読んでから書いてみましたが、こちらは既存のライブラリで実現できることを一通り把握できる良い本でした。

Rubyによるクローラー開発技法 巡回・解析機能の実装と21の運用例

今回実装したクローラは、以下のような動作を行います。

• All Modules (Ansible Documentation) からリンクされている、末尾が _module.html のファイルをすべて辿る
• ページの冒頭に New in version 2.0. と書いてあれば、Ansible 2.0 の新モジュールと見なす
• Options の表に、(Added in 2.0) と書いてあるパラメータがあれば、Ansible 2.0 の新オプションを含むモジュールと見なす
• サイドバーの表示をチェックして、そのモジュールが属するカテゴリを判別する
• クロールした結果を、Markdown 形式で出力する

このクローラのソースコードは Gist で公開しました。引数を変えれば、過去のバージョン（1.9 とか）で追加されたモジュールの一覧や、次の 2.1 で追加されるモジュールの一覧を作ることもできます。興味のある方は手元で動かしてみてください。

クローラのソースコード(Gist): Crawler to create a list of new modules in Ansible 2.0

クローラの実行結果

2016年3月20日現在、All Modules (Ansible Documentation) には495件のモジュールが掲載されています。

今回のクローラを実行した結果、Ansible 2.0 で追加されたモジュールは194個、以前からあるモジュールに追加されたオプションは155個でした。あれ、200個以上の新モジュールって話では……？　まあ、大体合ってるからいいですよね。

結果をざっと見てみると、確かにクラウド関係のモジュール（Cloud Modules）が130個と、群を抜いて多かったです。他には expect や find なんていう、以前からありそうな名前のモジュールも、2.0 で新たに追加されたようです。Zabbix 関係のモジュールもありますね。

ざっと見てみて、使いたいモジュールが見つかったら、思い切って Ansible 2.0 に移行してみるのも良いかもしれません。その際は、以前に書いた Ansible 2.0 移行事例をご参考ください（職場ブログの宣伝）。

recruit.gmo.jp

以下、クローラのソースコードと、自動生成したモジュール、オプションの一覧です。目次ありの一覧を見たい方は、Qiita に同じ内容を貼っておいたので、そちらをご覧ください。

qiita.com