無印吉澤

Site Reliability Engineering(SRE)、ソフトウェア開発、クラウドコンピューティングなどについて、吉澤が調べたり試したことを書いていくブログです。

Elixir のテスティングフレームワーク ExUnit, ESpec の比較

f:id:muziyoshiz:20161122004038p:plain

Elixir でのコードを書くにあたり、テスティングフレームワーク ExUnit および ESpec を調べてみました。

ExUnit は Ruby で言うところの Test::Unit で、ESpec は RSpec のようです。調べてみた結果、自分は ExUnit を使うことにしたのですが、せっかくなので調べたことをまとめておきます。

比較表

ExUnit ESpec
インストール方法 Elixir, Phoenix Framework 標準 mix で追加する(espec, espec_phoenix)
テストの書き方 主に assert で真偽チェック expectshould で文章のように書ける
テストのグループ化 describe が使える(Elixir 1.3 以降) context, describe, example_group が使える
実行方法 mix test mix espec
テスト結果 失敗した行番号が含まれる 失敗した行番号が含まれない
テスト名の制約 日本語を使えない 日本語を使える

以下は、この比較表の詳細です。

ExUnit

インストール方法

Elixir の標準に含まれており、mix.exs に何も足さなくても使えます。

また、Phoenix Framework では mix phoenix.new を実行する際に、データベース接続のためのヘルパーや CaseTemplate が自動生成されます。これにより、ExUnit のテストケースを使ったモデルのテストが可能になっています。

テストの書き方

主に assert または refute での真偽チェックとして書く必要があります。

defmodule ElixirSampleTest do
  use ExUnit.Case
  doctest ElixirSample

  test "the truth" do
    assert 1 + 1 == 2
  end
end

標準出力をテストするための ExUnit.CaptureIO やログ出力をテストするための ExUnit.CaptureLog といった便利機能もあります。これらを使う場合も、最終的には assert を呼ぶ必要があります。以下は CaptureLog の使用例です。

  test "example" do
    assert capture_log(fn ->
      Logger.error "log msg"
    end) =~ "log msg"
  end

テストのグループ化

Elixir 1.3 から describe マクロが追加されて、テストのグループ化が簡単になりました。RSpec の describe と同じようにグループ化できます。

以下は ExUnit.Case のドキュメント に記載された例です。

defmodule StringTest do
  use ExUnit.Case, async: true

  describe "String.capitalize/1" do
    test "first grapheme is in uppercase" do
      assert String.capitalize("hello") == "Hello"
    end

    test "converts remaining graphemes to lowercase" do
      assert String.capitalize("HELLO") == "Hello"
    end
  end
end

実行方法

mix test で実行します。

$ mix test
..

Finished in 0.05 seconds
2 tests, 0 failures

Randomized with seed 37255

テスト結果

テストに失敗した場合、失敗したテストの開始行と、assertion に失敗した行の番号を表示します。

例えば、以下のように絶対失敗するテストを書いたとします。

defmodule ElixirSampleTest do
  use ExUnit.Case
  doctest ElixirSample

  test "the truth" do
    assert 1 + 1 == 2
    assert 1 + 1 != 2
  end
end

実行結果はこうなります。

$ mix test
.

  1) test the truth (ElixirSampleTest)
     test/elixir_sample_test.exs:5
     Assertion with != failed, both sides are exactly equal
     code: 1 + 1 != 2
     left: 2
     stacktrace:
       test/elixir_sample_test.exs:7: (test)



Finished in 0.04 seconds
2 tests, 1 failure

Randomized with seed 648187

テスト名の制約

test にも describe にも、日本語名(正確には、アトムに変換できない文字列)を使えないようです。例えば、以下のようにテストを書いたとします。

  test "1足す1が2に一致する" do
    assert 1 + 1 == 2
  end

これを実行すると、以下のようなエラーが返されます。

$ mix test
** (ArgumentError) argument error
    :erlang.binary_to_atom("test 1足す1が2に一致する", :utf8)
    (ex_unit) lib/ex_unit/case.ex:411: ExUnit.Case.register_test/4
    test/elixir_sample_test.exs:5: (module)
    (stdlib) erl_eval.erl:670: :erl_eval.do_apply/6
    (elixir) lib/code.ex:370: Code.require_file/2
    (elixir) lib/kernel/parallel_require.ex:57: anonymous fn/2 in Kernel.ParallelRequire.spawn_requires/5

BDD ではテストメソッド名に日本語を使おう、という意見があったりしますが、ExUnit では難しいようです。

ExUnit の参考ページ

Programming Phoenix: Productive, Reliable, Fast

Programming Phoenix: Productive, Reliable, Fast

ESpec

インストール方法

Elixir 標準ではないので、antonmi/espec のページにあるように mix.exs に追加する必要があります。

def deps do
  ...
  {:espec, "~> 1.3.0", only: :test},
  ...
end

あとはいつもの mix deps.get でインストールしたあとで、以下のコマンドを実行して spec/spec_helper.exs を生成すれば準備 OK です。

$ MIX_ENV=test mix espec.init

Phoenix Framework で ESpec を使う場合は、mix.exs に espec_phoenix を追加します。これにより、モデルによるデータベース接続を伴うテストなどが可能になります。

テストの書き方

expect … to の組み合わせか、should を使って書きます。RSpec だと今は should は推奨されていないようですが、ESpec についてはそういう記載は見当たりませんでした。

defmodule ContextSpec do
  use ESpec

  example_group do
    context "Some context" do
      it do: expect "abc" |> to(match ~r/b/)
    end

    describe "Some another context with opts", focus: true do
      it do: 5 |> should(be_between 4, 6)
    end
  end
end

テストのグループ化

context、describe、example_group が使えます。RSpec に似ていますね。

antonmi/espec に載っている例(下記)では example_group に説明文が付いていないですが、付けることも可能なようです。

defmodule ContextSpec do
  use ESpec

  example_group do
    context "Some context" do
      it do: expect "abc" |> to(match ~r/b/)
    end

    describe "Some another context with opts", focus: true do
      it do: 5 |> should(be_between 4, 6)
    end
  end
end

実行方法

MIX_ENV=test mix espec で実行します。ただ、antonmi/espec に従って mix.exs に設定を追加すれば、MIX_ENV=test は省略できるようになります。

$ mix espec
.

    1 examples, 0 failures

    Finished in 0.07 seconds (0.06s on load, 0.01s on specs)

    Randomized with seed 654062

テスト結果

テストに失敗した場合、失敗したテストの開始行を表示します。 assertion に失敗した行の番号は表示してくれません。

ExUnit の場合と同じように、絶対失敗するテストを書いてみます。

defmodule ElixirSampleSpec do
  use ESpec

  it "the truth" do
    expect(1 + 1) |> to(be 2)
    expect(1 + 1) |> to_not(be 2)
  end
end

すると、実行結果はこうなります。test の開始行の番号(4行目)しか出てきません。

$ mix espec
F

    1) ElixirSampleSpec the truth
    /Users/myoshiz/devel/elixir_sample/spec/elixir_sample_spec.exs:4
    Expected `2` not to equals (==) `2`, but it does.

    1 examples, 1 failures

    Finished in 0.11 seconds (0.1s on load, 0.01s on specs)

    Randomized with seed 728628

これくらいの内容なら、テスト結果からどの行かわかりますが、テストあたりの行数が長くなると辛くなってきます。長いテストコードは書くべきでない、という設計思想なんでしょうか。

コマンドライン引数などで、この動作を変更できるのではないかと思ったのですが、方法を見つけられませんでした……。これ、個人的には致命的に不便だと思うんですけど、他の人はどうなんですかね。

テスト名の制約

ESpec の it や describe は、テスト名に日本語を含めても、問題なく動作しました。

ESpec の参考ページ

まとめ

ESpec で書いたテストのほうが読みやすくなるのですが、総合的に考えて、個人的には今後は ExUnit を使うことにしました。

ExUnit は標準で採用されているために導入の手間が少なく、グループ化などの基本的な機能は備えているので、十分かなと。テスト失敗したときに行番号が表示されるなら、ESpec でも良かったんですけどね……。Elixir の練習のために admiral_stats_parseradmiral_stats_parser_ex に移植していて、作業が終わりかけたところでこれに気付いたときは愕然としました。

ちなみに、Elixir には、Ruby における Cucumber 相当の “WhiteBread” や、FactoryGirl 相当の “ExMachina” もあるようです。そのうち、これらも試してみたいと思います。

自作ツールのアイコンをクラウドワークスのコンペ機能で発注してみた

f:id:muziyoshiz:20170212132356p:plain

きっかけ

自作ツール(Admiral Stats)のリリース直後に、サポート用アカウント @admiral_stats を Twitter に用意していたのですが、やり取りが増えてきたので、デフォルトのたまごアイコンをそろそろ卒業したくなってきました。

以前から、アイコンのアイディアは考えていたのですが、良い案が全然浮かばなかったので、この機会にクラウドソーシングサービスを使ってみました。今回の記事は、クラウドワークスでの発注〜デザイン完了までと、使ってみての感想についてのお話です。

クラウドソーシングサービスを探す

まず、どこに発注するかですが、国内だとランサーズとクラウドワークスが有名だと思います。既存の案件をざっと見た感じ、アプリアイコンは1〜2万円くらいが相場なんでしょうか。5千円という案件もありました。

アイコンデザインだけなら、英語圏で頼むことも可能だろうと思い、海外のクラウドソーシングサイトも見てみました。ただ、数があまりにも多いのでよくわからず……。

最近読んだ SOFT SKILLS のなかで「自分のロゴをクラウドソーシングサイトに発注しよう」という話題のなかで取り上げられていた、以下の2社に目を通してみました。

例えば、Fiverr で “icon” で検索すると、「アプリアイコン5ドルで1個、訂正1回まで」みたいな仕事を受けてくれるデザイナーがすぐ見つかりました。これは極端な例としても、さすがに英語圏だと価格が大きく違うようです。

クラウドソーシングサービスを選択する

海外もいいな、と思いつつ、とりあえず希望するデザインを日本語で文章にしてみることに。

  • 「艦これアーケード」というアーケードゲームのプレイデータを管理する Web アプリのアイコンデザイン
  • デザインのモチーフは、操舵輪、歯車、カード、桜吹雪など、艦これアーケード自体のモチーフに近いものから選んでほしい
  • データの蓄積をイメージさせる、他のモチーフと組み合わせても OK
  • favicon としても使いたいので、小さいサイズで表示しても問題ないデザイン
  • 色は、艦これアーケードのロゴと同様の青系、またはアイコンに使われている黄色〜茶系
  • フラットデザインのUIに含めても、違和感のないデザイン

うん……。具体的なアイディアがなにも浮かんでなかったので、曖昧すぎですね。

ここまで書いて「艦これアーケードというゲーム自体や、そのモチーフについて英語で説明するのは面倒すぎるな」と気付いて、国内のサービスへ発注することに決定。

ランサーズとクラウドワークスのどちらにするか、で悩んだんですが、評判で検索してもよくわからず。なんとなく安価な印象があったので、今回はクラウドワークスのほうを選びました*1

仕事を依頼する

アプリのアイコンをどうやって発注するのかわからずに悩んだ末に、「デザイン > キャラクター・アイコン・アニメ > アイコン作成」カテゴリを選択。

f:id:muziyoshiz:20170212132948p:plain

依頼の形式は「プロジェクト形式」と「コンペ形式」から選べるんですが、デザインの具体的なアイディアがなかったので、複数の案が集まることを期待して「コンペ形式」を選択。まあ、結論から言うとあまり多くの案は集まらなかったんですが……。

応募期限は、当日の24:00から、14日後の24:00まで選択可能。今回は14日後を選択。

そして、仕事の内容を入力して、最後に予算の選択です。

f:id:muziyoshiz:20170212133019p:plain

32,400円のスタンダードプランがおすすめ、とありますが、趣味の、広告収入もないアプリでそこまで払う気にもなれず。かといって、カスタムで安くしすぎるのも良い案が集まらなそう(僕が逆の立場なら手を出さなそう)なので、標準のプランで一番安いエコノミーを選択しました。案件を目立つところに表示するためのオプションが色々ありましたが、低予算なのでオプションは無しで。

すべての登録が完了すると、メンバー(受注者)向けに以下のようなページが公開されます。

crowdworks.jp

ちなみにこのページ、募集中は受注者にしか見られないのですが、募集終了後は受注者以外(ログインしていない人)にも全公開されます。それが嫌ならプラス8,000円払うと非公開にできるみたいです。

発注〜デザイン決定までの流れ

1月16日に発注して、デザインが決定するまでの流れは、以下のような感じでした。

日付 できごと 提案人数 提案件数
1/16 1人目のデザイナー(過去の受注実績なし)から、最初のデザイン提案 1 1
1/20 1人目のデザイナーから、別デザインの提案 1 3
1/21 2人目のデザイナー(過去の受注実績20件くらい)から、最初のデザイン提案 2 4
1/22 提案済みのデザインに対するコメントを元に、1〜2人目のデザイナーから、別案の提案あり 2 10
1/24 2人目のデザイナーの案をベースにしようと決めて、更にやりとり 2 13
1/25 2人目のデザイナーに、最終案の微調整を依頼 2 17
1/25 採用する案を決めたので、締切を 1/26 に早めた 2 17
1/26 1人目のデザイナーから、別デザインの提案 2 18
1/26 採用デザイン決定 2 18

最初の4日間は提案してくれたデザイナーが、過去の受注実績のない1名のみだったので、1万円が無駄になるか?と心配だったのですが、あとから受注実績のあるデザイナーが提案してくれて、その方とデザインを微調整して最終決定、という流れでした。最終的には以下のデザインを採用しました。

f:id:muziyoshiz:20170128164643p:plain:w300

後から気づいたのですが、コンペ機能だと「この案にしよう」と思っても即決はできないんですね。終了を翌日の24:00に早めることしかできませんでした。まあ、これはデザイナー側への配慮なんだと思います。

感想

クラウドワークスのコンペ機能で発注してみた感想を三行でまとめると、こんな感じでした。

  • デザインを気軽に頼むには便利
  • 依頼金額を最低ラインにすると、品質の低いデザインにお金だけ取られる可能性が高そう
  • 信頼できるデザイナーがいるなら、同じ額を払ってそっちに頼むほうがいい

もう少し細かい感想は、以下の通りです。

提案人数と提案件数はだいぶ違う

コンペ方式だとデザインが採用されない限りは報酬0なので、デザイナーの視点で考えると、提案件数がすでに多い案件には参加したがらないでしょう。

そう考えると、発注者としては、気に入ったデザインが出てくるまでは提案件数を少なくしておきたいです。しかし、以下の理由でそうもいかない、というのがわかりました。

  • 気に入らなかったデザイナーの追加提案を拒否することはできない
    • この人のデザインは自分には合わないな、と思っても、追加提案は拒否できません
  • デザインの微調整を依頼すると、提案件数が跳ね上がる
    • コンペの途中でも、相手とメッセージをやり取りして、デザインを微調整してもらうのが一般的なようです
    • しかし、微調整してもらったが結局希望に合わなかった、という場合、提案件数が増えただけで新規提案が来にくくなる、というデメリットがあります
  • 提案保証人数を当てにするなら、スタンダードまで上げないと意味がない
    • 提案保証人数1名だと、実績の少ないデザイナーで埋まってしまう
    • 提案保証人数を2名以上にしたいなら、3万の「スタンダード」まで上げる必要がある
    • しかし、そこまでの金額を払うなら、個別に頼んだほうがよくないか?

今回の場合、デザインが大きく異なるのは5件のみで、残り13件はそれの微調整でした。

特定のデザイナーを指定して依頼できるなら、そのほうが双方にとって良い

自分でデザインすることを考えれば、1万で今回のデザインが得られたのには満足しています。

しかし、ある程度実績のあるデザイナーを探して、個別に(クラウドワークスの機能で言うなら「プロジェクト形式」で)提案したほうが、双方にとって良いだろうな、と思いました。まあ、当たり前の話かもしれませんけど……。

先日の 秋葉原IT戦略研究所の勉強会 で、このサークルの同人誌のデザインをしているデザイナーの方にこの話をしてみたところ、

受注側としてはポートフォリオがないと仕事が来ないので、最初のポートフォリオを作る手段としては、デザイナーにとって良い手段なのではないか。

との感想をもらいました。まあ、確かにそうかも。

発注側としては、コンペ形式での実績を見て、良さそうな人に個別で依頼するのがよいのかもしれませんね。次の機会があったら、プロジェクト形式の方を試してみたいと思います。

*1:あとから知ったのですが、後述するエコノミープラン、クラウドワークスは 10,800 円ですが、ランサーズは 21,600 円でした。

LT で艦これアーケードと Admiral Stats の色々を話してきました

f:id:muziyoshiz:20170128164643p:plain

秋葉原IT戦略研究所という、アニメ x IT ネタで同人誌を出したり勉強会を開催しているサークルがあります。そのサークルの勉強会「ShangriLa Meetup」の LT で、Admiral Stats の話をしてきました。

akibalab.connpass.com

スライド

Admiral Stats は、私が趣味で作っている、「艦これアーケード」というアーケードゲームのプレイデータを可視化するツールです。公式サイトにはない「時系列でのデータ表示機能」、「他提督(プレイヤー)との比較機能」などを備えています。

スライドの章立てはこんな感じです。

  • 艦これアーケードってどういうゲーム?
  • Admiral Stats の紹介
  • Admiral Stats の中身の解説
  • Admiral Stats を公開してみた結果

艦これアーケードをプレイしている提督の方は、Admiral Stats を試してもらえると嬉しいです。未プレイの方は、公式サイトのプレイムービー あたりを見て、興味が湧いたらプレイしてみてもらえると(ゲームのファンとして)嬉しいです。

www.admiral-stats.com

信用できる社内 Wiki をつくるために守ってほしい、たったひとつのルール

f:id:muziyoshiz:20170109184841j:plain

このページについて

この記事は、以前書いた「社内Wikiに情報を書くときに守ってほしい、たったひとつのルール」の続編です。前回は、個々のページをどう書くべきかという話をしましたが、今回は社内 Wiki 全体を信用できるものにする方法について考えます。

muziyoshiz.hatenablog.com

想定する環境

この記事は、ソフトウェア開発プロジェクトに関する Wiki が社内にあって、そこに各人がドキュメント(仕様書や手順書など)を書けるようになっている環境を想定しています。

私自身、ソフトウェア開発のときしか Wiki を使わないので、具体例もそのような環境に寄っています。ただ、ある程度は社内 Wiki 全般に通じる話かと思います。

ルール:「更新され続ける」ページと「更新されない」ページをはっきり分ける

ここ1年ほど社内プロジェクトをいくつか渡り歩いていたのですが、個人的には、このルールが徹底されている Wiki ほど「信用できる」と感じました。

具体的な実現方法はいくつかありますが、例えば、Wiki のホーム画面の上半分を「更新され続ける」ページへのリンク、下半分を「更新されない」ページへのリンクにします。以下は、ホーム画面の例です。

# 更新され続けるページ

- [[用語一覧]]
- [[サービス仕様]]
- [[インフラ構成]]
- [[アプリケーション構成]]
- [[開発ルール]]
- [[手順書]]
- [[主要機能の解説]]

# 更新されないページ

- [[ミーティング議事録・資料]]
- [[ユーザーストーリーごと(または機能ごと)の設計]]
- [[リリース履歴]]
- [[運用作業履歴]]
- [[障害履歴]]
- [[技術検討メモ]]
- [[現在はメンテナンスされていないページ一覧]]

誤解を避けるために強調しておくと、これはWiki を「信用できる」ページと「信用できない」ページに分けよう、という話ではありません。信用できないことがはっきりしているなら、そのページは消したほうが良いでしょう。

そうではなくて、これは「完全に信用できる」少数のページと、「条件付きで参考にできる」多数のページに分けよう、という話です。以下では、説明のために、もう少し具体的な話をしてみます。

「信用できる」とは?

この記事で言う「信用できる」という形容詞は、「信用できる技術者」を指すときの「信用できる」と同じような意味だと思ってください。

私が知っている信用できる技術者を思い出すと、大抵以下のような長所を備えています。

  • 専門分野について正確で詳しい知識を持つ
  • わからないことは素直にわからないといい、必要な調査やテストを行って、あとからそれを補う

同様の状態を Wiki で実現したものが、この記事でいう「信用できる Wiki」になります。

「更新され続けるページ」については、そこを読むだけで正確な情報を知ることができて、読み手はソースコードを読んだりする時間を節約できます。

一方、「更新されないページ」については、過去のある時点では事実だった(あるいはその書き手が事実だと信じていた)情報ですが、現在では正しいかわからない情報です。その場合も、読み手は、条件付きでその情報を参考にすることで、調査にかかる時間を節約できます。

逆に「信用できない」とは?

上で挙げた信用できる技術者の長所をひっくり返すと、以下のように、信用できない技術者になります。

  • 専門分野について、曖昧な知識しか持たない
  • わからないことについても「○○に違いない」と断言する

大抵の Wiki は放っておくと、信用できない技術者に似た、信用できない Wiki になってしまいます。例えば、こんな感じです。

  • 仕様ページに書いてある仕様が、その後の機能追加の際に更新されなかったために、現在の仕様と違う
  • ローカル開発環境の構築手順書が、ゼロから動作確認されなかったために、他の人が試すと動かない

こうなると、普通の人は「ソースコードを読むしかない」、「実際に試してみるしかない」と判断して、その Wiki を避けてしまいます。信用できない技術者に、相談する人はいないですよね。

その社内 Wiki には、実際には役に立つ情報もあったかもしれないのに、全体の信用を失ってしまったために役に立つ情報まで読まれなくなるとしたら、それはもったいないことです。

ルールを運用するためのヒント

このルールをチーム全体できちんと運用するためのヒントを、いくつか挙げておきます。

ヒント(1):「更新され続けるページ」は極力少なくする

このルールを採用する場合、何か機能をリリースするたびに、その機能に関連する「更新され続けるページ」はすぐ更新する必要があります。忙しい時期でもこのルールを守れるように、更新され続けるページは極力少なくしておいたほうがよいでしょう。

例えば、以下のような情報は、更新し続けるメリットが、更新作業のコストを上回ると思います。

  • 用語一覧
    • そのプロジェクト固有の用語一覧。主に、新メンバへの説明用。
  • サービス仕様
    • 顧客に提供するユーザーマニュアルや、サポート対象 OS・ブラウザの情報など。
  • インフラ構成
    • ネットワーク構成図や、システム構成図、IP アドレス一覧など。
  • アプリケーション構成
    • コンポーネント一覧、バッチ一覧、データベース定義書など。
  • 開発ルール
    • そのプロジェクトで採用する開発プロセス、開発用ツール、コーディング規約、テスト基準など。
  • 手順書
    • システム構築のための手順や、日常的な運用作業の手順など。
  • 主要機能の解説
    • そのプロジェクトで特に難しい機能や、わかりにくい機能の理解を助けるための解説記事。

ヒント(2):更新し続けられないと判断したら、「更新されないページ」に移す

理想的には、「更新され続けるページ」はできるだけ多いほうが良いです。ただ、開発が多忙になったり、逆に開発が一段落して開発者の人数が減ったりすると、更新にかけられる時間は減ります。

そういう場合は、どのページを残すかチーム内で議論して、更新しきれないページは「更新されないページ」に移しましょう。Wiki のページ数よりも、「その Wiki は信用できるかどうか」のほうを重視すべきです。

例えば、以下の階層にある「機能Aの解説」ページを最近更新できてない、と気付いたとします。

  • 更新され続けるページ
    • 主要機能の解説
      • 機能Aの解説

この場合、そのページを「更新されないページ」以下の階層に移す、という具合です。「機能Aの解説」ページの先頭(「このページについて」欄)に、更新できなくなった時期とその事情を書いておくと、読み手の助けになるでしょう。

  • 更新されないページ
    • 現在はメンテナンスされていないページ一覧
      • 機能Aの解説

ヒント(3):「更新されないページ」を「更新され続けるページ」に格上げしたいときは、必ず書き換える

更新されないページを書いているうちに、分量が多くなり、内容も充実したように思えるので、「更新され続けるページ」に格上げしたくなることがあります。例えば、以下のような場合です。

  • ある機能の設計に関するページが、その機能に関するよいまとめに思えるので、主要機能の解説ページに格上げしたい。
  • ある障害の原因を特定するためにソースコードを調査したときのメモが、ソースコードのよい解説に思えるので、主要機能の解説ページに格上げしたい。

しかし、元々これらのページを書き始めた目的は「主要機能の解説」ではないため、余分な情報が多く含まれている可能性が高いです。分量が多いほど更新が大変になるので、元のページとは別のページを作り、更新し続ける必要がある部分だけ残して、リライトしたほうがよいでしょう。

また、そもそも、有用な情報をすべて「更新され続けるページ」にする必要はありません。「更新されないページ」のなかに「技術メモ」のようなカテゴリを作り、そのなかに「2017年1月時点の技術メモ」のような形で残しておくという方法もあります。

ヒント(4):ルールを守るための責任者を立てる

上記のルールを徹底するためには、ある程度の強権が必要になります。

例えば、チームメンバが以下のようなことを始めてしまったときに、誰かがあるべき状態に戻す必要があります。このような行動は、各人の自主性に任せていてもなかなか防げません。意見の衝突が起こるからです。

  • 「自分がよく使うページだから」という理由で、ホーム画面にリンクを書き足す。
  • 「誰かが更新すべき情報だ(自分は更新しないけど)」という理由で、「更新され続けるページ」にページを足す。
  • 自分が必要だから更新し続けているページがあるが、責任を押し付けられたくないので、「更新されないページ」の中に残し続ける。

このような衝突を解決するために、ルールを守るための責任者をチーム内に立てて、その責任者は「このルールを守るためであればどのようにページを編集してもよい」と明言しておくのが良いと思います。メンバから異論がある場合はその責任者を中心に議論し、ときどき細かい運用を見直します。

この責任者は強権が必要で、かつ Wiki のほとんどすべての編集にざっと目を通す必要があるため、チームリーダが兼務するのが一番良いと思います。それが難しい場合は、簡潔な文章を書くのが得意な人を任命するのがよいでしょう。

まとめ

今回は、信用できる社内 Wiki をつくるために、私が個人的に実践している基本的なルールをご紹介しました。

このルールの目的は、「読み手が Wiki に期待するレベルを適切にコントロールすることで、読み手が Wiki に幻滅し、無視してしまうのを防ぐこと」です。Wiki のページを「完全に信用できる」少数のページと、「条件付きで参考にできる」多数のページに分けることで、読み手にとって信用できる Wiki をつくることができる、ということを具体例を挙げてお話ししました。

もしも、自分が後から参加したプロジェクトに「信用できない社内 Wiki」があったらどうするか? 元から使われている Wiki を大きく書き換えることもできないので、その場合は特定のページ以下を「信用できるサブ Wiki」として育てるのがよいと思います。このルールを色々アレンジしてみてください。

今回は社内 Wiki 全体の話をしましたが、個々のページを「信用できる」ように書く方法については、以前書いた以下の記事をご参考ください。

muziyoshiz.hatenablog.com