ぽよメモ

ファッション情報学徒の備忘録.

Ansibleの冪等性について深く考えたことはありますか?

はじめに

 僕は今,修士論文の執筆に向けて構成管理ツールと冪等性についての論文を複数読んでいます.それらを踏まえて,一般によく見られるAnsibleへの誤解についての自分の見解,そして2019年現在,構成管理ツールについてどういった研究がされているかを簡単に述べていきたいと思います.

冪等性

 そもそも冪等性とは「ある操作を一回行っても,複数回行っても,結果が変わらない」という概念です.例えば,

  • 例えば1や0と任意の自然数のかけ算
    •  N \times 1 = N \times 1 \times 1 = N \times 1 \times 1 \times 1= \cdots
    •  N \times 0 = N \times 0 \times 0 = N \times 0 \times 0 \times 0= \cdots
  • 絶対値の計算
    •  abs(x) = abs(abs(x)) = abs(abs(abs(x))) = \cdots

などが冪等性を持った処理に当たります.

Ansibleにおける冪等性

 さて,Ansibleのモジュールを使用した操作はよく冪等であると言われています.ここで,Ansibleにおける「冪等」とは何でしょうか?Ansibleの用語集*1を引いてみます.

An operation is idempotent if the result of performing it once is exactly the same as the result of performing it repeatedly without any intervening actions.

訳すなら,「一度実行した結果が,介入する操作無しで繰り返し実行した結果とまったく同じならば,操作は冪等である」という感じでしょうか*2.うーんなんとなくいいかんじに思えますね!(?

 しかしこの「まったく同じ」というのは何を要求するのでしょうか.例えばlineinfileモジュールを用いて,あるファイルにある行が一文あるということを宣言したとします.

- lineinfile:
    path: /path/to/hoge
    line: "Some line"

実行したとき,必ず一度はその存在を確認するためにファイルにアクセスする必要があります.すると,その行がある場合も無い場合も,Linuxではそのファイル(ここでは/path/to/hoge)のatime,つまりアクセス日時が更新されてしまいます.また,(オフに設定しない限り)実行の度に対象のホストへログも書き込まれます.これは「冪等性」を満たすのでしょうか?

冪等性は主観によって決まる

 おそらくほとんどのケースでは,atimeの更新やsyslogへの書き込みのような,求める操作に伴う暗黙的な副作用は問題にならないでしょう.この場合には「(当人から見て)冪等性は満たされている」と言えるかと思います.しかし逆に,(あるのか知りませんが)atimeが重要で容易に更新されて欲しくないケースにおいてはどうでしょうか?もしかすると,「(当人から見て)冪等で無い」と考えるかも知れません.

 このように,構成管理ツールにおける冪等性というものは,実際にはその結果を観測した人の主観に左右されます.冪等なモジュールであるからといって,得られる結果が完全に何もかも実行前と同じとは限らないということに留意した上で,こうしたツールと付き合っていく必要があるでしょう.

 このような必ずしも何もかもが完全に同一とはならない現実のシステムにおいて,「冪等」という概念をそのまま適用することは非常に難しいと言わざるを得ません.あまりしっくり来る定義を見つける事ができなかったのですが,天才*3から教えてもらったRFC7231の4.2.2*4がなかなかしっくりくるなと思ったので紹介します.ここではGETやPUTなどのHTTPリクエストについて,どのような場合にそのリクエストを「冪等」と見なすかを述べています.

Like the definition of safe, the idempotent property only applies to what has been requested by the user; a server is free to log each request separately, retain a revision control history, or implement other non-idempotent side effects for each idempotent request.

つまり,「冪等」と判定する要素は,ユーザが要求した属性についてのみであり,それに伴うサーバサイドでの副作用(例えば各リクエストについてログを取るなど)は感知しないということのようです.Infrastructure as Codeの文脈において考えてみても,各ツールはユーザが要求した属性(例えばファイルの存在とか)についてのみ冪等であることを保証できるように努力し,それに伴う副作用(サーバサイドにログが残る,atimeが更新される…etc)については保証しない,という考え方をすれば,比較的まともな「Ansibleにおける冪等性」への理解を得られるかと思います.

モジュールの冪等性

 現状構成管理ツールのあるモジュールによる操作が,(他の何らかの操作の介入を受けなかったとしても)完全に冪等性を保証することは知る限りでは証明されていません*5.つまり,Ansibleによる操作が完全に冪等であることを,誰も保証してくれません.もちろんIssueには冪等性(idempotence)に関するものも多くあり,努力はされていますが,最終的には自分で検証してなんとかするしかありません.
 このような現状なので,当然どのモジュールのドキュメントにも,「これは冪等なモジュールです」とは書いていません.Issueを漁っていると,過去に「冪等かどうかドキュメントに書いてくれ」というものが上がっていました.

github.com

これに関連したIssueコメントは以下です.

github.com

非常に短いメモが残されているだけなので,実際のその場での議論などは分かりませんが,

  • 冪等でないモジュールもある
  • でもそれらのために多大な労力を払って冪等かどうかを表示するのはコストが高すぎる
  • 今のところ何もしない

というような決着を迎えたようです.以降これに関連したIssueは探しましたが見つからず,Ansibleの方向性として冪等性のしっかりとした証明は目指さず,あくまで努力目標であるということが伺えます*6.活躍するドメインから考えても,これはあくまで実務上のツールであり,理想を追い求める物ではないので,この判断は正しいことだと思います.

 とはいえ,冪等な操作を売りにしているツールにしては,そのやり方でみんな納得しているのか?という気持ちがあります.

Playbookの冪等性

 全てのタスクが冪等であったとしても,複数のタスク・ロールを束ねたときに,全体を通して冪等になるとは限りません.例えばあるミドルウェアをインストールするというロールと,そのミドルウェアをアンインストールするというロールを同時に使用すれば,毎回インストール→アンインストールを繰り返すことになり,冪等性が保たれなくなります*7

 こうした事象を避けるためには,

  • 一つのRoleの責務を小さくかつ明確にすること
  • Ansible GalaxyなどでインストールしたRoleの中身に一度は目を通しておくこと

などが重要かと思います.

構成管理ツールについての研究の今

 それなりの数に目を通したのですが,ちゃんと研究になっているものとしては以下の3種類に分類できると考えました.現状この分野の研究はほぼPuppetのものに限定されており,Ansibleは構成管理ツールとしての紹介がされているのみです.

冪等であるかどうかをテストする系

 2013年にChefのCookbookを対象に,冪等性検証フレームワークを提唱した論文です.LXCを使用して実際にCookbookを実行するのですが,ただ二回実行するというような方法ではなく,STGという状態遷移グラフを構築して様々な実行パターンを検証します.状態の変化の検知にはOhai*8を使用していたようです.

Testing Idempotence for Infrastructure as Code | SpringerLink

2016年に上の論文の結果を受けてPuppetでの冪等性検証フレームワークの提唱をしたのが下記の論文です.Ohaiを参考にした上で,straceやptraceを使って任意のファイルの変更まで追いかけたのが特徴です.

Asserting reliable convergence for configuration management scripts

結果の可視可もよく出来ています.

citac.github.io

同じく2016年にPuppet向けの冪等性検証フレームワークとしてRehearsalというものを提唱した論文です.これは単にPuppetコードを実行するのではなく,Puppetの各リソースを彼らが提唱したファイル操作をするための小さなDSLに置き換え,Puppetの非決定的な実行順序による操作のコンフリクトを検証できます.

Rehearsal: a configuration verification tool for puppet

難しいのでしっかりとは読み込めていませんが,そもそも構成管理ツールのある操作は任意のファイルへの操作であると考えると,これは割と面白いアプローチかと思いました.

品質モデルを提唱する系

 2016年にMSRというリポジトリマイニングの国際会議にて提唱された,Puppetコードのコードスメル*9に関する研究です.いわゆるバッドプラクティスを検知して「匂う」コードを見つけようというものです.

Does your configuration code smell?

下記の論文では,Puppetコードの品質モデルを提唱しています.実際に開発者らへのアンケートからモデルを定義し,自社・他社のPuppetエンジニアによる品質の分類と,品質モデルによる分類を比べて,ある程度正確な品質モデルを定義する事が出来たと述べられています.

How good is your puppet? An empirically defined and validated quality model for puppet - IEEE Conference Publication

セキュリティ系

 以下の論文も又コードスメルの検出なのですが,内容がよりセキュリティに寄っています.

2019.icse-conferences.org

以下のブログに簡単なまとめがあります.

jagijagijag1.qrunch.io

IaCに関する研究はブルーオーシャン

 ここでは構成管理ツールに関する研究に絞っていますが,IaC(というかDevOps)という分野自体が若く,研究はあまり進んでいません.実務と結びついた領域であるために,研究者が手を出しにくい分野なのかもしれません.出すなら今ですよ!(?

 特にそのツールや概念に詳しい研究者を集めることは容易ではなく,GitHubなどから開発者らにメールを送ってアンケートに答えてもらう,など,泥臭いことが多々行われています.その回答率も芳しくなく,結果の信頼性としてもかなり微妙と言わざるを得ません.Ansibleはユーザコミュニティも活発で,実務で使用しているプロフェッショナルが多数います.研究にはもってこいなのでは? 🤔

まとめ

  • Ansibleに限らず,構成管理ツールにおける冪等性というものは,使用者の主観によって左右される
  • 今のところ,Ansibleモジュールが真に冪等であることは証明されていない
  • モジュールが冪等だから!と適当にやっていると容易に冪等性を失う
  • IaCは実務に関わる部分が大きく,研究者にはなじみが薄いため,論文を書き放題
    • ツールへの造詣が深いエンジニアの意見を使って論文が書けるのは企業の強み
    • 是非いかがですか?

*1:https://docs.ansible.com/ansible/2.9/reference_appendices/glossary.html?highlight=idempotency

*2:ニュアンス違ったらすいません

*3:弊ラボのドクターです

*4:tools.ietf.org

*5:これは研究者の怠慢であるかもしれませんね

*6:続報があるとか何か知っておられる方いらっしゃれば教えてください

*7:こういうのをAnsibleのdry-run時に検知する方法とかないんでしょうか?

*8:github.com

*9:qiita.com

deanishe/awgoを使って簡単にAlfred Workflowを作る

はじめに

 これはGo3 Advent Calendar 2019,7日目の記事です.

qiita.com

Alfred Workflowとは?

 macOS向けの多機能ランチャーであるAlfredの自動化のためのプラットフォームです.Alfredとは,簡単に言ってしまうとmacOSのSpotlightの機能強化版です.

www.alfredapp.com

 過去に以下のようなものを作りました.

poyo.hatenablog.jp

poyo.hatenablog.jp

poyo.hatenablog.jp

最後の一つはAlfredのUIを一切使っていないので少し毛色が違いますが,上2つの様な,

  1. 何らかのトリガーとなるコマンドに対して
  2. 選択肢を提示し
  3. ユーザの選択によって何かアクションを起こす

というものを作りたくなったときに便利に使えます.なお,Alfred本体は無料なのですが,それとは別にPowerPackと呼ばれる拡張パッケージを購入することで使えるようになります.現在のメジャーバージョンでのみ使えるSingle License(25ユーロ),永久ライセンスのMega Supporter(45ユーロ)という二つの形態のライセンスがあるのでお好きな方を購入してください.

www.alfredapp.com

Alfred Workflowの仕組み

 様々な形態のWorkflowがありますが,基本的には用意されているコンポーネントGUIで繋いでいき,あるコンポーネントから別のコンポーネントへ,文字列を受け渡して様々なアクションを起こします.

 自作のスクリプト/バイナリを使ってAlfredのUIを使用したい場合,Script Filterというコンポーネント内でそのスクリプト/バイナリを実行し,所定の形式を持つJSON*1を標準出力へprintします.そのJSONをAlfredが読み取り,良い感じにUIを表示して,選択されたオブジェクト(の中の,次のコンポーネントへ渡す引数となる文字列)を接続されているコンポーネントへ受け渡します.

 実行できるアクションには様々な物があり,

  • ブラウザで検索
  • URLを開く
  • 任意のアプリケーションで開く
  • 任意のスクリプトを実行する

などなど,多数のアクションが用意されています*2.こうしたアクション以外にも,クリップボードへコピーしたり,通知をだしたりも出来ます.便利ですね.

Alfred WorkflowとGo

 Alfred Workflowで動かすアプリケーションをGoで書くというアプローチは,数年前から行われています.

techblog.kayac.com

blog.tsub.me

kyokomi.hatenablog.com

これらのサイトでも述べられていますが,

  • シングルバイナリになるので簡単に配布して簡単に使える

という部分が最も大きいです.全てをシェルスクリプトで書ける猛者ならまだしも,どんなモジュールが入っているか分からないPythonPerlで頑張るよりも簡単かつ安全かと思います.

github.com/deanishe/awgo

 今までは自分の手で書いたstructをjson.Marshal()していましたが,便利なライブラリが開発されていました.

github.com

Alfred3および4用のライブラリで,どちらでも使うことが出来ます*3

 また,表示するアイテムの出力だけでなく,様々な機能のサポートが含まれています.長くなるので今回は紹介しませんが,一通り調べてみたので機会があればそれについても記事を書きたいと思っています.

チュートリアル

以下の環境で実行しています.

  • macOS 10.15
  • Go 1.13
  • Alfred 4.0.6
  • github.com/deanishe/awgo v0.21.0

あまり良い題材を思い浮かばなかったので,今回はこのAlfred Workflowで使った依存パッケージのライセンスを閲覧できるAlfred Workflowを作ってみようと思います.ビルドしたバイナリを配布する場合,使用した各モジュールのライセンスに則って著作権表示等が必要となります*4

f:id:pudding_info:20191206182837g:plain
選択したモジュールのLICENSEを表示

リポジトリはこちら

github.com

1. 空のWorkflowを作る

左下の+からBlank Workflowを選択すると新しいWorkflowを作成するウィンドウが開きます.

f:id:pudding_info:20191205224816p:plain
Blank Workflow

Bundle idはとにかく一意な値であれば良いので,自分の持っているドメイン等があればそこから適当な値を自分で考えれば良いと思います.ここで記述した内容は後からでも変更可能なので,あまり迷う必要はありません.

2. 実行するアクションを並べる

 依存パッケージとライセンスの取得には以下のパッケージを利用させて頂きます.

github.com

これは出力方式としてJSONを選択することができ,その場合各モジュールの名前とLICENSEファイルの中身を取得できます.閲覧のためにはその中身を一旦ファイルに出力する必要があるので,以下の様な構成とします.

  1. モジュール名とライセンスファイルの中身から表示するアイテムを作成するスクリプトを実行
  2. 選択したモジュールのライセンスが文字列で渡されるので,これをWorkflow内のテンポラリディレクトリに出力
  3. そのファイルを規定のプログラムで開く

加えて,Modifierを使ったときの例も示したいので,1の後にCommand + Enterを押すことでそのモジュールのURLをブラウザで開く,というタスクも追加します.

コンポーネントは,右クリックして出てきたメニューから選択して作成できます.各コンポーネント間はドラッグで紐付けることが出来ます.虫のマークはデバッグコンポーネントで,そのコンポーネント間でやりとりされる引数や変数を見ることが出来ます.

f:id:pudding_info:20191206163051p:plain
コンポーネント一覧
コンポーネントの設定はそのコンポーネントをダブルクリックで開けます.

f:id:pudding_info:20191205230549p:plain
Script Filterの設定

f:id:pudding_info:20191205230746p:plain
Write Text Fileの設定

Open File,Open URLコンポーネントはデフォルトのままです.Command+Enterでアイテムを選択したときにOpen URLへ動作を分岐させる方法は,コンポーネント間の接続(エッジ)をダブルクリックすると出てくるメニューから,使用するModifierにチェックを入れるだけです.他のModifierもあるので,更に様々な操作を行うことが出来ます.

3. info.plistを手に入れる

次に,左にあるWorkflow一覧から,このWorkflowを選び,オプションメニューからFinderで開くを選択します.

f:id:pudding_info:20191206163352p:plain
Open in Finder

info.plistというファイルがあると思うので,それを次に作るGoのプロジェクト内にコピーします.このファイルを単体で編集するのは骨が折れるので,基本的にコンポーネントの操作等はAlfredのUI上で行い,それをその都度Goのプロジェクトへコピーするようにしています.

4. Goでプログラムを書く

 まずはプロジェクトを作り,deanishe/awgoをインストールします.

$ mkdir sample-alfred-workflow
$ cd sample-alfred-workflow
$ go mod init
$ go get github.com/deanishe/awgo

Songmu/gocreditsが吐くJSONは以下の様なフォーマットなのでそれに合わせてstructを作ります.

{
  "Licenses": [
    {
      "Name": "モジュール名",
      "URL": "URL",
      "FilePath": "ファイルパス",
      "Content": "LICENSEの中身"
    }
  ]
}

license.goとして以下の内容を記述します.特に難しいところは無いはずです.

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
)

// 各モジュールごとのLicenseを表すstruct
type license struct {
    Name     string
    URL      string
    FilePath string
    Content  string
}

// モジュールごとのライセンスを全て内包するstruct
type licenseJson struct {
    Licenses []license
}

// 与えられたパス名からライセンスを読み取り,ライセンスの一覧を返す
func getLicenses(path string) ([]license, error) {
    contents, err := ioutil.ReadFile("./credits.json")
    if err != nil {
        return nil, fmt.Errorf("%s does not exists.\n", path)
    }
    var licenses licenseJson
    if err = json.Unmarshal(contents, &licenses); err != nil {
        return nil, fmt.Errorf("Failed to parse %s.\n", path)
    }
    return licenses.Licenses, nil
}

ようやくdeanishe/awgoを使ってメインのロジックを書いていきます.とは言っても,この程度のAlfred Workflowならば非常に簡単になります.

package main

import (
    "fmt"
    "os"
    "strings"

    aw "github.com/deanishe/awgo"
)

var (
    // このプロジェクト全体で参照するaw.Workflow
    wf *aw.Workflow
)

func init() {
    // 初期化時にインスタンスを生成する
    wf = aw.New()
}

func run() {
    licenses, err := getLicenses("./credits.json")
    if err != nil {
        // wf.Fatal~~は,エラーメッセージを出力して終了させる
        wf.FatalError(err)
    }
    for _, c := range licenses {
        // ループを回して一つずつItemを作っていく
        // Itemの持つ各メソッドはItem自身を返すのでメソッドチェーンで書ける
        item := wf.NewItem(c.Name).
            // Argは選択されたときに次のコンポーネントへ渡す引数となる文字列
            Arg(c.Content).
            Subtitle(strings.Split(c.Content, "\n")[0]).
            // Valid(true)としないと選択できないので注意
            Valid(true)
        // そのアイテムがCommand+Enterで選択されたときの動作を変更する
        item.Cmd().
            Arg(c.URL).
            Subtitle(fmt.Sprintf("Open %s in browser", c.URL)).
            Valid(true)
    }
    // 与えられた文字列でアイテムをフィルタリングする
    args := os.Args
    if len(args) > 1 {
        // https://godoc.org/github.com/deanishe/awgo/fuzzy
        wf.Filter(args[1])
    }
    // 最終的に表示すべきアイテムが無かったときに表示するエラー文
    wf.WarnEmpty("No credits were found.", "Try different query.")
    // 標準出力へ最終的なJSONをプリントする
    wf.SendFeedback()
}

func main() {
    // 内部でpanic等をうまくハンドリングしてくれる
    wf.Run(run)
}

wf.NewItem()を呼び出した時点で表示するアイテム一覧の中にそのアイテムが追加されるため,どこかにappendしたりする操作は不要です.

6. パッケージングする

 ググっているとAlfredのUI上からExportしないとAlfred Workflowとしては動作しないというように言われていますが,実は.alfredworkflowというファイルの実態は単なるzipファイルです.そのため,単に必要なファイルを全てzipでアーカイブにして拡張子を変えるだけで済みます.今回は以下の様なMakefileを用意しました.

SHELL := /bin/bash

PLIST=info.plist
CREDITS=credits.json
EXEC_BIN=sample-alfred-workflow
DIST_FILE=sample.alfredworkflow
GO_SRCS=$(shell find -f . \( -name \*.go \))

all: $(DIST_FILE)

$(CREDITS): go.sum
  gocredits -json . > $(CREDITS)

$(EXEC_BIN): $(GO_SRCS)
  go build -o $(EXEC_BIN) .

$(DIST_FILE): $(EXEC_BIN) $(CREDITS) $(PLIST)
  zip -r $(DIST_FILE) $(PLIST) $(CREDITS) $(EXEC_BIN)

単にmakeとするだけでsample.alfredworkflowが生成されます.

$ make
# 関連付けされているのでAlfredが開いてインストールできるはず
$ open sample.alfredworkflow

7. CI/CDする

 GitHub Actionsが正式リリースになっているのでこれを使いましょう..github/workflows/release.yamlとして保存します.

name: Release
on:
  push:
    tags:
      - "v*"
jobs:
  release:
    runs-on: macos-latest
    steps:
      - name: Checkout source codes
        uses: actions/checkout@v1
        with:
          fetch-depth: 1

      - name: Setup Go environment
        uses: actions/setup-go@v1
        with:
          go-version: 1.13

      - name: Restore cache if available
        uses: actions/cache@v1
        id: cache
        with:
          path: ~/go/pkg/mod
          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
          restore-keys: |
            ${{ runner.os }}-go-

      - name: download modules
        if: steps.cache.outputs.cache-hit != 'true'
        run: go mod download

      - name: Build
        run: make

      - name: Create new release
        id: create_release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          draft: false
          prerelease: false

      - name: upload release asset
        id: upload-release-asset
        uses: actions/upload-release-asset@v1.0.1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ steps.create_release.outputs.upload_url }}
          asset_path: ./sample.alfredworkflow
          asset_name: sample.alfredworkflow
          asset_content_type: application/zip

これでタグを付けると以下の様にリリースされます🎉

f:id:pudding_info:20191206181142p:plain
First release!

macOSのセキュリティ

 Catalinaでは,署名されていない,インターネットからダウンロードしたバイナリの実行をデフォルトでブロックします.そのため,この方法でAlfred WorkflowをGitHub Releasesからダウンロードすると以下の様に警告を吐かれます.

f:id:pudding_info:20191206181331p:plain
警告その1

システム環境設定 > セキュリティとプライバシーから実行を許可して再度実行するとまた警告が出ます.

f:id:pudding_info:20191206181521p:plain
警告その2

ここで「開く」を選択すると,ようやく次からAlfred Workflowを使用できます.
別にマルウェアなどは仕込んでいないので安心してください……

deanishe/awgoの微妙なところ

  • 何もかもstructなのでテストしづらい
    • aw.Workflowがあらゆるビジネスロジックを担っている巨大structなので剥がしづらい
    • 小さいInterfaceを自分で定義していくのがいいかも

  • グローバルなaw.Workflowを使い回す設計なのでテストしづらい
    • wf.Run(fn func())の中で実行することを想定しているので,この設計以外で使えない

  • wf.SendFeedback()がDIの機構を持たないので出力をテストしづらい
    • 直接stdoutに書き込んでいて外側からインジェクション出来ない
    • wf.Feedback.MarshalJSON()で生成されるJSONをテストするだけで凌ぐ…?

  • wf.NewItem()がgoroutine safeじゃない
    • 内部的には全てのアイテムはwf.Feedbackが管理しており,wf.NewItem()wf.Feedback.NewItem()を呼んでいる
    • FeedbackのItemsに単に作ったItemをappendしており,goroutineで普通に叩くと壊れる https://github.com/deanishe/awgo/blob/master/feedback.go#L421
    • 普通にaw.NewItem()みたいなのとwf.AddItem()みたいなのがあれば十分だったと思う

  • wf.NewItem()が返すItemがデフォルトでvalid=falseになっている
    • valid=falseなオブジェクトはUIに表示できるが選択できない(エラーメッセージとかを表示するのに使う)
    • デフォルトがfalseなのはAlfredの文脈的には直感に反する
    • 作者の意見:github.com

紹介しきれていない機能

リポジトリに上がっている参考実装がかなりためになります.https://github.com/deanishe/awgo/tree/master/_examples

などなど

まとめ

  • Alfred WorkflowをGoで書くならdeanishe/awgoは機能が豊富で便利
  • GitHub ActionsでCI/CDも出来る
  • macOS Catalinaのセキュリティ機能はかなりおせっかい
  • deanishe/awgoは癖が強いのでテストはちょっと色々考える必要がある

皆さんの面白いAlfred Workflowをお待ちしています.


*1:www.alfredapp.com

*2:www.alfredapp.com

*3:Alfred2まではJSONではなくXMLを使って居ました.これはdeprecatedになっています.Alfred3および4はJSON形式に対応しています https://www.alfredapp.com/help/workflows/inputs/script-filter/xml/

*4:加えてGoの自体のライセンス(BSD3条項ライセンス)も含める必要があります.これ知らなかったので,今後気をつけます…

内部向けWikiに技術記事を書くモチベーションと意義,そして今の悩み

はじめに

 これはあくあたん工房アドベントカレンダー2019,2日目の記事です.技術の欠片もないポエムです.

 他の記事はこちらからご覧頂けます.

adventar.org

内部向けWikiとは?

 例えばサークル・研究室・企業など,何らかの集団において,そのメンバーが様々な情報の共有に使用するドキュメンテーションツールを指しています.どういったツールを使っているかは,その集団の特性等に大きく左右されると思います.例えば

などなど,色々なツールが開発・利用されています.僕自身はサークル・研究室共にesa.ioのお世話になっています.
 まだ学生の身なので企業内部でのWikiの使われ方はよくわかりませんが,今回の記事の中には通ずる部分もあるだろうと思っています.

ありがちな問題

 こういったツールの問題として,基本的に「よく書く人と全く書かない人に分かれる」というのがあると考えています.書かない人たちからは

  • 書くことが無い(何を書いたら良いか分からない)
  • ググれば出てくる
  • 書かなくてもみんな知ってる

などの声を聞くことがあります.特に,「既にググれば出てくるであろう知識」を書くモチベーションは欠けてしまいがちになっているように感じます.

ググって出てくるから書かなくて良い?

 そもそも,ググれば出てくる==書く必要が無いは本当に真なのでしょうか.

 現代のインターネットは非常に便利で,どう考えてもマイナーな内容でもググれば数件はヒットするという世界です.しかし一方で,現代は情報が氾濫しており,情報の取捨選択が難しいという問題が起きています.ゆえに自分に代わって情報の取捨選択をしてくれるキュレーションメディアが流行し,乱立していると言えるでしょう.

 また,Google検索にはノイズも多く,

  • プログラミングスクールの薄っぺらい記事
  • StackOverflowの機械翻訳サイト
  • 既に使えなくなっている古代の知識で書かれたブログ

などなど,分かっている人にとってはただただ邪魔な,分かっていない人にとってはより混乱の原因となるノイズが多数紛れています*1

 まとめると,ググって出てくる情報は

  • あまりにも数が多く,その価値の判断が難しい上に時間がかかる
  • 多数のノイズを効率よく弾くだけの基礎知識が必要

ということです.内部向け技術記事ではこの逆を目指していきたいというのが今回の記事の主旨です.

みんなに書いてもらうために

身内だけで通じる価値観を理解する

 一部のスーパープログラマを除いて,大抵の技術者は世の中からほとんど認知されていません.その実力がどれくらいなのか,何に詳しいのか,どういうことに興味があるのか,そういった情報は基本的に明らかではありません. そのため,インターネット上に溢れる大抵のまとめ記事は価値が非常に低く見積もられがちです*2

 一方で,特定の集団内においては互いのことをある程度知っています.そのため,その人の書く記事がたとえ同じようなまとめ記事だったとしても信頼度が大きく変わってきます.もちろんその信頼性は多くの場合身内だけに通じるものなので,外部に公開するかどうかはそれを書いた本人がその価値を見積もって考えれば良いと思います.少なくとも,内部に向けた情報を記述するに当たって,ググれば出てくる情報の焼き増しをすることを恐れる必要は無い,ということは言えると思います.

 つまり「ググれば出てくるから書かない」と言われたら,

  • インターネット上の赤の他人の記事よりは,身内の記事の方が信頼できる(質問もできる)
  • 既存の記事をまとめただけのものであっても,自分で探す手間が省けるから助かる

と言いましょう.

気軽に書ける雰囲気を作る

僕は少し前にサークル内向けに以下の様なLTをしました.


 そもそも書くハードルを低くしておかなければ誰も書いてくれません.そのためには使いやすいツールを用意することが不可欠です.僕は前述したようにesa.ioを活用させて頂いており,その利便性に日々感謝しています.おすすめです.

 また,どういった内容を書くのかについて,小さいチームなので特にルールを定めていません.弊サークルではメンバーごとに自分のネームスペースを持っているため,ただのメモ書きのようなものも好きに書けるようにしています*3.大きいチームでの運用に当たってはこの辺りの「遊び(余裕)」の調整が必要かとは思います.

既にある記事の更新を躊躇わない

 知識はどんどん古くなっていきます.記事として残した情報も,いつかは古くなってしまう物です.「これは自分より詳し い〜〜さんが書いた物だから」とか「自分が書いても間違ってるかも」とか思わずに,どんどん更新されていくべきです.

 簡単なtypo,実行するコマンドの変更,一部APIの使用方法の変化,…etc,細かい変化は常に起こり続けています.気が付いたら「バージョンXXからはYYはZZになりました」程度で良いので更新していければ,記事が陳腐化していくことを避けれるのではないでしょうか.これは個人ブログではなかなかできないので,多数の人間が関わって管理しているからこそ得られるメリットであると考えています.

 集団で知識を蓄えていくというのはそういうことであり,上で述べた「書くハードル」にも近いですが「更新するハードル」も低くあるべきです.そのためには個人間で変な縄張り意識を持たず,自分の書いた記事への他の人からの変更を歓迎することが大事かも知れません.GitHubでPull Request出してくれた人にThank youと言うのと同じような文化が技術記事にも根付くと嬉しいです*4

書くメリットを意識する

 「そうは言われても書いたからって給料が上がるわけじゃないが?」みたいなことを言われればそれはそうなのですが,そもそも書くメリットを認識できていない人が多いのかなという気がしています.個人的に思っているメリットについていくつか書きます.

  • 自分自身の理解の向上に繋がる
  • 書くことで集団内での自分のブランディングができる
    • 〜〜に詳しい人,みたいな
  • 他人に教えるときに「とりあえずこれ読んで」と言える
  • 他人に理解してもらう文章を書くのは難しいので,普段からそれを意識して書いておくことは,対外発表の練習にもなる

これは内部Wikiではなく,公開するブログに書く場合も同様なので,そもそも他人に見てもらうものを書く習慣があるかどうかの違いが大きいと思います.不特定多数に対して公開するブログと違って,明確にその集団のレベルアップに貢献できるという意味で,内部Wikiの方がメリットはわかりやすいかも知れません.

 これは別にメリットではないんですが,僕は普段色々なブログ等にお世話になっているので,何か貢献できたらいいなという気持ちでブログを書いています.「GitHubでコントリビュートするのは難しいけど」みたいな人は,感謝の気持ちを込めてブログを書きましょう.

あるべき内部Wikiの姿

 何か調べたいときに,まず最初に調べる場所が内部Wikiになるのがベストだと個人的には思っています.

 そこには既に見知った人間がまとめた情報があるはずで,自分でググりながら真偽を確かめていく過程を省くことが出来るからです.その上で,その内容では足りない・間違っているなど追加/修正の必要が生じれば記事を更新する,そもそも記事が無く今後も必要となると判断したなら記事を書く,そういうサイクルをうまく回していけると,ナレッジベースとしての内部Wikiがうまく機能するのではないでしょうか.

今の悩み

どのレベルから知識を共有するか

 当然個人間のスキルセットには差があるため,全員がどこまで理解していて,どこから分かっていないかを決めることは難しいです.例えばDockerの使い方について記事を書くとして,僕は「仮想化」というもので何を実現したいのか,どういうことが起きるのかをなんとなく理解していますが,今までそういったやり方に触れてこなかった人にはまずそこの説明から必要になってきます.しかしそれを書くためにじゃあLinuxカーネルってなんだ,そもそもLinuxってなんだ,OSとは?コンピュータとは?みたいなことまで書くかと言われれば,(僕自身の知識不足ももちろんありますが),時間的にも,費用対効果的にもしないでしょう.

記事が増えすぎたときにどうなるのか

 今はせいぜい数百程度の記事しかなく,一覧で見てもなんとかなります.しかしこれが数千,数万に膨れ上がったら?それはソフトウェアで解決するのだろうか?というのは気になっています.

 もちろん検索はあるので,キーワード検索やタグ検索などの方法をとることは可能です.しかし,「検索したいワードが分かっていないと検索は出来ない」という問題があり,そもそもどう検索すれば良いのかわからないシチュエーションでは内部Wikiもうまく効果を発揮できません.そもそもそれ以上時間をとらずに済むからWikiに書いたのに,「Wikiに書いてある内容を検索するための質問」とかをされるようになったら本末転倒です.

結局当人以外が記事を更新しない

 特に研究室などでは,数年ごとに人が入れ替わります.そのため,過去に誰かが書いた記事がそのまま放置され,閲覧も更新もされない死んだ情報になってしまう可能性があります.属人性を排除するために記事として残したのに,その情報の修正/更新が属人化してしまっては元も子もありません.

 更新されない理由として

  • どういう記事があるのか知らない
  • それを更新して良い物なのか判断できない

などがあると思っていて,今どういう記事が存在するのかをなんとなくでいいので把握しておくことが重要だと思います.僕は新しく記事を書いたときにSlack等で「こういうのを書きました」みたいなことを一言言うようにはしていますし,後輩と話しながら「じゃあそれ追記しておいて」とかは気軽に言うようにしています.とはいえ,そもそもSlackすらまともに見てくれない人たちや,自分がいなくなった後に入ってくる人たちにまで知らせることは難しいです.僕は他の人がどういうものを書いたのか見るのが好きで,更新があれば軽く覗いたりコメントしたりしているのですが,全員がこれをやる必要があるとまでは絶対言えないので,何かうまい対策が必要だなと感じています.

 また,内容を盲目的に信じ切ってしまう人が出てくるのも課題だと感じています.「書いてあるから」「そうらしいから」などと信じ切ってしまう人が出てくると,その情報は更新もされずただただやってみたが上手くいかなかった「使えない情報」として処理されたり,時代錯誤なやり方が残って負の遺産となってしまう可能性があります.個人のレベルはまちまちなので仕方ないと言えばそれまでなのかも知れません.

最後に

 情報が氾濫している現代では,情報の価値はそれを書いた人を自分がどれくらい信頼できるかで決まっていると感じています.同じ内容を知らない学生が言うのと,親しい友人が言うのではその重みが違うように,インターネット上でも知っている人の書いた情報と,赤の他人が書いた情報の間には大きな隔たりがあるはずです.
 内部Wikiは現代では貴重な「ある程度信頼できる人が集まって作ったナレッジベース」であり,そこに情報を蓄積することは,自分だけでなく組織全体にとって意味があることです.全員が発信していける場を作り,全員で高め合っていけると最高ですね.


*1:僕はuBlacklistのお世話になっています

*2:一部例外もあります.何書いてもバズる人というのが世の中にはいます

*3:スマブラのキャラ対策・論文のメモ等色々乱立しています

*4:Qiitaの編集リクエスト機能はまさにこれのはずなのですが,全然うまく機能しているように思えません.悲しい