猛烈に暑かったり暑くなかったりするなか皆様いかがお過ごしでしょうか。自宅のエアコンが故障して修理待ち半月の id:tmd45 です。
先月、5 年間使い続けてきた Qiita:Team から esa へ、情報共有ツールの乗り換えを行いました。80 名ほどの全社移行となかなか大きなプロジェクトだったので、ここに記録を残したいと思います。
なぜ乗り換えに至ったか
フィードフォースの情報共有文化
もともと弊社では Qiita:Team 以前にも、Redmine や社内サーバに構築した Wiki システムを利用し、ナレッジの蓄積と共有を習慣化していました。すばらしいですね。
そこにビジネスチャット(当初は HipChat、現在は Slack を利用)を導入、フロー型の情報が増えていきました。Redmine や社内 Wiki のようなストック型のナレッジだけでなくフロー型の日常をまとめられる場所が欲しくなり、当時台頭してきた "今風" の情報共有ツールとして 2014年4月から Qiita:Team を使いはじめました。
この頃の記事を見てみると、日報をはじめ、これまで Redmine や Wiki には書きづらかった(書かれたとしても個人メモとして閉じていた)「〇〇やってみた」「〇〇読んでみた」などの情報や、ちょっとした振り返りをまとめた記事が並んでいます。
完全なストック型(Wiki 系)と完全なフロー型(チャット系)の中間をツールとして、Qiita:Team はとてもよく機能しました。社内の情報共有文化がこれだけ育っているのも、そういう場を用意できていたことが大きいと思っています。
うれしいことに日報や手順書、ポエム、ノウハウなどさまざまな記事が気軽に投稿される弊社でしたが、社員が 80 名近くになるとその情報の整理に課題を感じるようになりました。
フロー型の情報とストック型の情報について、参考記事
抱えていた課題
このときの課題とは、大量に増えた記事のなかから必要な記事が見つけられない ことでした。
記事が埋もれてしまっても検索などでかんたんに見つけられればいいのですが、残念なことに Qiita:Team の機能では 検索ノウハウのある人間であれば頭を使ってなんとか意図した記事を見つけられるものの、そうでなければほとんど目的の記事を見つけられないような状況になりました。 記事を探すというだけで "頭を使う" 必要があるというのはなかなかヘビーです。
必要な記事が見つからず、似たような内容の記事が量産されてしまいました。埋もれてしまった古い記事はアーカイブをされることもなくときどき情報検索の邪魔をするようになりました。似たようでちょっと違うタグが乱立しました。流れてしまう情報をなんとかしようとグループ機能を試してみたこともありましたが、グループに閉じてしまうと今度はグループを跨いだ情報の流し読みが困難になりました。
ちなみに一時期(2015 年頃)の Qiita:Team は機能として "タグの階層化" が可能でしたが、これに頼ったタグ整理を行ってしまったことも、後々のタグ運用が難しくなる要因であったと思います。いつのまにか(2019 年確認)タグにスラッシュを入れると入力チェックに引っかかって記事が保存できなくなったことにはモヤっとしました…
タイトルに絞った部分一致やタグによる検索は可能でしたが、これが上手く機能するように、あとから膨大な記事やタグを整理するのは、なかなか骨の折れる作業です。
ナレッジマネジメントに特別な興味のないひとも徐々に「なんとなく使いづらいな…」と感じるようになっていました。
動き出した移行プロジェクト
社内 Slack に "情報共有ツールをなんとかしたい" チャンネルが生まれたのが 2018/10/18、私がそこに Join したのが 2018/11/13 でした。
他のツールに乗り換える前に、現状のナレッジマネジメントのルールやポリシーを整備したほうがいいのではという議論は何度も発生しました。Qiita:Team のプロジェクトページなどを使って INDEX 記事を作成したり、タグについて議論したり、Slackbot に特定の発言をしたときに記事 URL を返すようにさせたり…
プロジェクトページで INDEX を作ると、今度は "プロダクト用のプロジェクトページ"(紛らわしいですね 😅)が埋もれてしまうということもありました。これは一社内に多くのプロダクトを持っている弊社ならではかもしれません。
このまま「工夫」でなんとかするには、情報整理が得意な人間が「がんばり」続ける必要がありそうでした。情報整理のポリシーなどを定めたとしても、定期的にそれをリマインドし、自警する誰かが必要になるのではないかと思いました。
そのため他の情報共有ツールについて少しずつ調査やトライアルをしていきました。
検討した情報共有ツール
たくさんあるので詳細は割愛しますが、わりと最後まで有力候補だったのが Kibela でした。開発の動きが活発に見えましたし、信頼感のある著名なエンジニアの方が関わっていることも知っていたので強い興味を持っていました。その他、挙がったツールをご紹介しておくと DocBase, marchily, Scrapbox など、そして esa です。
いろんなツールを検討するなかで、解決したいことと求める条件をざっくりと以下のようにまとめました。
- 記事検索のしやすさ
- 「プロダクト毎のグループ」と「社内活動毎のグループ」の区別(できれば)
- 「日報」との区別
- チームをまたいで誰でも全体を眺められる感じ
- ナレッジをマネジメントしたい
- エンジニアも総合職も使いやすい
何かを区別して分類したいというのは、つまりカテゴリなりディレクトリなりが欲しいということで、DocBase を試したときに「いいな」と思ったポイントでした。
またプロダクトでチームが分かれていても、情報を完全に分断してしまいたくないという思いが以前からあり、他のツールを触るなかでもよく気にしていたポイントでした。この部分は Qiita:Team のトップページのように、すべての情報が流れてザッピングできるものがよかったです。
そんなこんなで仕事の合間にいろいろ試していたら 2019 年も春になっていました。どのツールも一長一短なうえに、80 名近くのメンバーを一度に動かす POWER が必要です。当時の自分の Slack 発言曰く「移行したい、と、移行めんどくさいのはざま」でした。
esa に決めるまで
はざまに居る間もどんどん記事は増えていくので、その都度どうしたらその記事が埋もれずに済むか悩んでいました。ここでもまだ「Qiita:Team の記事を一斉に整理する時間をとれば…」みたいな話は出ていました。諦めが悪い(笑)
このへんの時期に他社さんで esa を導入したとか、(Qiita:Team から)esa に乗り換えたという記事を目にすることが増えました。
- Qiita:Teamからesa.ioに乗り換えました - LCL Engineers' Blog
- カルチャー崩壊と再構築。 Goodpatchが取り組んだ組織デザインの2年間 - 前編|naofumit|note
例のチャンネルメンバーのなかで「esa を使うとしたらどうやって使ったらカオスにならずに済むだろう」みたいな話をしていました。個人的にも(元から好きなサービスだったこともあり)なんとなく esa にしたいなぁと思い始めて、他社の事例を積極的に探しに行きました。
esa の中の人 (\( ⁰⊖⁰)/) がまとめている「esa トーク」の記事も穴が開くほど読みました。とくに大人数で利用されているピクシブさんと、カテゴリルールなどかなり具体的なお話をされていた Misoca さんの記事は、その後の移行のときにもとても参考になりました。
- esaトーク/サービスへの思いをesaに乗せて、ポエム駆動開発が捗る ─ Vol4.ピクシブ株式会社 様 - docs.esa.io
- esaトーク/日常もesaもハックするリモートワーカー集団 ─ Vol.5 株式会社Misoca様 - docs.esa.io
結果的に移行先の決め手となったのは、利用事例のわかりやすさと、すでに利用しているひとたちからの評判の良さかもしれません。
運命の 2019/04/24、まだ「移行めんどくさい」のはざまでウゴウゴしていた我々を動かしたのは、これまでナレッジマネジメントに悩んでいたチャンネルメンバー…ではない役員メンバーからのこんなお言葉でした。
"いまの情報共有ツールの使いづらさって、だれも問題に感じてないの?"
"ほかに良いツールがあるなら乗り換えたほうがいいよ!"
「ですよね!!?」という衝撃とともに個人的に火もついて、ここでやっと「情報共有ツールの移行、ワイが esa で進めたるでー!(POWER)」となったのでした。
社内への働きかけ
esa 移行を決心してから、社内への働きかけも行っていきました。
一番大切なのは 情報管理ツールを移行したい思いと目的 で、これは前述のようにいろいろ考えてきたので1つの記事を作って社内に共有しました。
また、移行プロジェクトに関わってくれたデザイナー氏が、移行の意欲を高めるために弊社のキャラクターと esa の (\( ⁰⊖⁰)/) を(勝手に)コラボしたイメージを作ってくれて、なかなかに社内の評判もよかったです。こういう「たのしい」工夫も大事だと思います。
そこからトライアルへの協力と、実際のアカウント移行のお願いなども同様に進めました。とくに新卒の若者たちは新しいツールを使いこなそう(`・ω・´)+という意欲も高く、積極的に使い方を聞きに来てくれたり、同期で共有したりしていて頼もしかったです。
社長にも「とりあえず1つ何か記事書いてください!」とお願いしたら、もともと Qiita:Team で書いていた週報をシュッと esa で書いてくれました。おかげでそれを読むためにアカウント登録するメンバーも増え、スムーズに移行できました。
データ移行のノウハウ
ここからはデータの移行で得た気づきなどです。 ご紹介しているスクリプトの利用につきましては保証しかねますのでご了承ください!
Emoji の登録
記事の移行より先にやったのが Emoji の登録でした。
Qiita:Team は Slack と連携して Emoji を同期させる機能がありますが、esa にはその機能はありません。 API で登録することができるので、ひとまず更新のことは考えず、その時点の Slack Emoji を吸い出して、esa に流しこみました。Slack Emoji を取ってくるスクリプトは拾いものなので割愛します、すみません。
流し込んだスクリプトはこちら。
すでに登録済みの Emoji に重複したキーワードだと 400 Bad Request
になります。また Slack は日本語キーワードでの Emoji 登録が可能ですが、esa のほうでは日本語キーワードには対応していないので、予め除外するか当該エラーでスキップさせましょう。
余談ですが、一度、Emoji の画像ファイルとキーワードをあべこべに登録してしまってカオスを生んでしまいました。いまはリカバリ済みです:(;゙゚'ω゚'):
記事データの移行
Qiita:Team の記事エクスポート機能(Owner のみ可能)で得られるデータは1記事=1JSON ファイルになっていて、メタ情報やコメントも含まれています。
esa に移行するために以下のようにしました。
▼記事作成・更新 API
esa パラメータ | 内容 | 注意点 |
---|---|---|
name |
記事タイトル | / や # は数値参照に置き換える(カテゴリやタグになってしまうのを避ける) |
category |
カテゴリ | (unsorted)/all 移行用に定義 |
body_md |
本文 Markdown | 1. パラメータとして指定できないメタ情報(記事作成日時など)を本文に追加する形で残す 2. 本文中の他記事 URL や画像 URL を置換 3. 本文中の ユーザID を小文字化( ScreenName に合わせるため) |
user |
記事作成者 | 記事作成者の ScreenName を指定 |
created_by |
記事作成者(上書き) | 同上。更新時に Owner 権限をもつ token でのみ上書き可能 |
▼コメント作成 API
esa パラメータ | 内容 | 注意点 |
---|---|---|
body_md |
コメント本文 Markdown | 記事本文と同様にメタ情報の追加と、他記事 URL、画像 URL、ユーザID の置き換えを行う |
user |
コメント作成者 | コメント作成者の ScreenName を指定 |
esa API の利用については 公式の開発者向けドキュメント を参照ください。
今回は「タグ」の移行をしませんでした。一度リセットして、混沌としたタグの整理ができればと思ったんですが、タグがなくなったことで意味がわからなくなってしまった記事が意外とあって、メタ情報と一緒に移行しておけばよかったな、と思いました。
インポートの流れとして 先に記事 URL や画像 URL だけ esa 上で作っておいて、記事本文を流し込む段階で記事中の URL の置換 を行いました。先に作った URL たちは中間データとしてテキスト(.tsv)に吐き出しました。口頭だとややこしいので詳しくは拙作のコードで。
使い捨て用に書きなぐったものなのでお恥ずかしいですが、なんか頑張ってるのが伝わればいいかなと思います 🙈
esa の API 利用はもちろんですが、画像取得のために Qiita:Team の API も利用します。
プロジェクトページ記事の扱い
Qiita:Team のプロジェクトページとなっている記事も1記事=1ファイルです。ただし通常の記事と、含まれている属性が若干異なるため注意は必要です。
基本的には通常の記事と同じく、渡せるメタ情報は渡して、Markdown の本文を投入するという感じで進めました。
もちろん esa には「プロジェクトページ」という概念はないので、適当に (unsorted)/projects
のようなカテゴリを定義してそこにまとめました。
実はメインの記事移行より先に、件数の少ないこちらを試していたため、結果的に URL の置き換え処理などすっかり忘れていました。INDEX の用途で利用していたページではこの置き換えを行わないとツラいと思いますので、お気をつけください。
プライベートグループの記事の扱い
プライベートグループでは、人事や役員会議などで扱う社内にも非公開の情報が含まれていました。これらは esa の決済連結機能を使って、別の esa チームを作成しデータ移行しました。
エクスポートした JSON データは、記事の所属するグループもパラメータとして持っているので、そこを見てファイルごと分別しておきます。
スクリプトが見当たらなくて自分でどうやったんだっけ…と思いましたが、雑に以下のコマンドで分類してました。ご参考まで 😇
$ cd path/to/export_articles $ ag -l '"url_name": "group_name"' ./*.json | xargs -I% mv % ./group_name
メンバーの移行とデータの移行のタイミング
今回は先にメンバー全員に、あるタイミングから新規記事は esa で作ってもらうよう案内しました(それゆえに Emoji の登録を先にやった)。
Qiita:Team 側に新しい記事が作成されなくなったのを見計らって、告知しつつ、記事データのエクスポートと、esa への投入を開始しました。
記事の参照は一時的に Qiita:Team と esa の双方を見ることになりましたが、"記事を書けない期間" を無くして移行できたのはよかったです。
esa と一緒に使っている便利ツール
事例といえば先駆者たちの esa 公式の紹介記事まとめ も大変助かりました。弊社でもいくつかの便利なツールを併用しています。
記事の自動作成「自動 esa やり機」
用意したテンプレートを元に、指定した曜日に自動で記事を生成してくれる Heroku アプリです。
弊社でも定期的なミーティングの議事録は、まず WIP の空記事を用意して、事前に議題を追記したり、話しながら記録したりということをやっています。Qiita:Team 時代からテンプレートを元に人が WIP 記事を作って共有していましたが、"誰か" がリマインドに気づいて記事を作成するといったことが不要になりました。
記事の作成と同時に指定した Slack チャンネルへの通知も行われることで、議題の追記のリマインドも兼ねていて非常に便利に利用しております!
Slack に記事 URL から概要を展開してくれる「Kujaku」
最近ツールの更新があってコメントURL からコメント内容も展開されるようになった、Slack x esa の情報共有を促進してくれる便利ツール。こちらもバックエンド部分は Heroku アプリです。
- FromAtom/Kujaku - GitHub
- Closedなesaの記事URLをSlackに貼ったら展開されるようにした - pixiv inside
- #esa のURLを展開してくれるKujakuで、コメントも展開できるようになりました。 - 文字っぽいの。
ログインしないと見られないようなクローズドなページの URL は、Slack に流してもその内容が展開されません。それを解決してくれるのが Slack の "Unfurling links in messages" という機能なのですが、その機能をかんたんに使えるようにしてくれたのがこのツールです。
これまでは URL と一緒にタイトルなども投稿してもらわないと「何?この URL…」となっていたのが、URL を貼るだけで手軽に共有できるようになったのはハイパー捗りました!
Emacs x esa 利用者におすすめ「emacs-helm-esa」
手前味噌ですが、esa 移行をきっかけに弊社の Emacs 使い id:masutaka26 が作った Emacs-Helm Interface もご紹介。
普段利用している環境から手軽に記事が探せるのは強いですね!よろしければお試しください。
Qiita:Team から移行して esa に思ったこといろいろ
なによりも課題であった「記事検索が上手くいかない」件はすっきり解決しました! 以前は言いづらかった「○○で検索してみてください!」というのが気軽に言えるようになってよかったです。
それ以外の部分を挙げてみたいと思います。
サポートの対応がフレンドリーかつ早い!
- esa のフィードバックフォームから投げたものに対する反応が早い
- 相談に対する回答も丁寧でとてもありがたい
- バグ報告したらすぐ直って
社内で2,3人鼻血出した素敵 - 情報セキュリティポリシー、運用ポリシーが公開されているので社内のPマークチェックもスムーズでした(確認にもご協力いただけて助かりました)
移行するデータ量が多いことは分かっていたので、先に esa の人に「たくさんデータ移行する予定なんですが大丈夫ですか…?」と連絡してみました。
移行当時の Qiita:Team メンバー数が 79 人、記事数が 5 万記事以上ありました(あとで気づきましたが、画像も相当な数とサイズがありましたね…)。esa の深谷さんや越川さん、赤塚さんからすぐにお返事をいただいて、とても助かりました。
導入時に助かったところ
- ドメイン制限が可能な Google ログイン
- G Suite 利用のため、ソーシャルログインでアカウント管理が一元化できてハッピーです
- 「添付ファイルに関するセキュアオプション」→ esaにログイン中のみ添付ファイルへのアクセスを可能にする
- esa 記事の外部公開ができなくなってしまうのは残念ですが、これがあると安心して業務情報をまとめられるので非常に助かります
- 「複数チームの連結決済」
- Qiita:Team 利用時から、人事や経営に関わるプライベートグループの運用がありました。これを引き継ぐため、メンバーを限定した esa チームを作り、連結決済の設定をしています
- 「Webhook・アプリ連携」での Slack 連携
- Qiita:Team のころから Slack にフィードを流すという運用をしていたので、同様のものがあり助かりました
導入時に困ったところ
アカウント登録のとき Name
と ScreenName
の違いが分かりづらかったようです。Name
のほうに氏名、ScreenName
にユーザID を入れてねー、という説明が必要でした。
また移行ならではですが、esa の ScreenName
では、Qiita:Team の ユーザ名
で使えた「英大文字」が使えません。そのため Qiita:Team で英大文字を含む ユーザ名
を利用していた場合には、すべて小文字に置き換えたものにしてもらいました。
アカウント登録の案内にこのような注意を書きました。どう判定させるかは移行スクリプトの作りに依ります。
大文字を小文字に置き換えた場合も「同一のIDである」と判断します :pray:
- Qiita で
ichiro3
→ esa でichiro3
⇒ OK ✅ (完全に一致)- Qiita で
Taro-san
→ esa でtaro-san
⇒ OK ✅(小文字になっただけ)- Qiita で
Hanako99
→ esa で99hanako
⇒ NG 💥(同一と判断できません)大文字・小文字とは別の話ですが、ハイフンやアンダーバーを使われている方は間違えないようにお気をつけください。
- Qiita で
Taro-san
→ esa でtaro_san
⇒ NG 💥(ハイフンがアンダーバーに。同一と判断できません)
Qiita:Team と esa の情報整理思想の違い
見出しのとおり、2つのツールは情報整理に対する姿勢が異なります。それゆえに移行して戸惑いの声が挙がったのは事実です。
これらの意見は「esa も Qiita:Team と同じようにすべき」という話ではありません。UI や使い方が変われば戸惑うひとがいるのは当たり前で、いずれ良い方向に慣れるか、悪い方向に慣れるか分かれます。
使い続けて感じる不便な点は、きちんとフィードバックすれば答えてくれるサービスだと思うので、そこは真摯にフィードバックしていきましょう 💪
Qiita:Team のトップページのように、すべての記事が流れていくようなものが欲しい。情報のザッピングがしたい
esa では "POSTS" のページがそれに当たりますが、Qiita:Team に慣れていたメンバーからすると「トップページ」から1ステップ踏まないとそれが見えないという戸惑いがありました。"POSTS" ページに移動しても、ソート順が意図した順でない(ソート順を変更するというリテラシーも必要になる)ことでも迷いが発生したようでした。
これについては、"HOME" の README 記事に便利リンク集を追加して、周知することでひとまず解決できました。
Recently Update が WIP も含むすべての記事の更新を age てしまう
これについては esa のコンセプトにどうしても馴染めないメンバーがいくらかいるという話でもあります。
まず 「下書き」機能が無いことで、以前より記事が書きづらい、公開もしづらくなった という声がありました。
不完全な状態では公開したくなく「下書き」のような非公開の状態で推敲を重ねて、キチンとした記事にしてから公開したい、という意見です。これを他人に強制するような人は見かけませんが「自分が記事を書くならそのようにしたい」と思うメンバーは年齢関係なくいる状況です。単純に下書き機能を「個人メモを置く場所」として使っていたという人もいました。
また、WIP で書いた記事を更新したときに、Recently Update で更新順として上がってきてしまうことに不便を感じる 声もあります。これは記事を書く方も、見る方もそうで「未完成の間は sage 進行したい」「更新された記事は知りたいけど ShipIt されてから読みたい」という状況です。 [skip notice]
しても Recently Update には流れてくるというのも戸惑われているようです。
読む側は、先程のザッピングの検索クエリと同じもので解決できるので、そちらを利用してもらっています。
書く側に対しては、気にせずガンガン更新しちゃいなよ!と意識改革していくしかないかなと思っています(自分は未完成でも気にしない星人)。
内部 URL でタイトルが展開されるのは便利だった…
Qiita:Team では、Qiita:Team 内の URL を貼るだけで、記事の表示時にリンク先記事のタイトル(と作成者のアイコン)が自動で展開されていました。"リンクされた記事" のタイトルを修正したときに、"リンクしている記事" 側を修正しなくてよいのは大変便利でした。
情報整理をしていると、よりわかりやすいタイトルに修正したくなることも多いですし、そういう記事に限っていろんなところから参照されていたりして…
いまでもこの機能は欲しいなーと思います(たしか esa にもフィードバックを送らせていただいたと思う)。
他人の記事をかんたんにいじれてしまう
これは最近不安を訴える人が減ってきたので、みんな慣れてきたのかもしれません。
Qiita:Team のときは「共同編集の記事」という区別があったり、「編集リクエスト」の機能があったため、うっかり他人の記事を触ってしまうということがありませんでした。これに慣れていると、逆にどの記事でも誰でもいじれてしまうのは、不安があったようです。
編集履歴から内容をロールバックすることもできるし、(自分のようなおじさんから言わせれば)昔からある Wiki だってそういうものですよ、という感じで、こちらも意識改革をしていくのがよいと思いました。
誰でも触れるおかげで、記事を書いた人に依存せずに情報の整理ができるというのはとても良い点だと感じます。
記事の Delete が出来てしまうことに不安を持つ人は多いかもしれませんが、まず記事の削除自体が2ステップ踏む UI になっていて「うっかり」することは少ないのではないかと思います。
さいごに
情報共有ツールの移行で得られた結果は以下のようなものです。
- 検索で記事が見つけやすくなった
- ナレッジの階層化ができるようになった
- ナレッジの構造化を意識するようになった
- フロー情報とストック情報を区別できるようになった
- 移行をきっかけに記事の整理が行われた
問題を感じることに鈍感にならず、今後も「日々混沌、日々進化1」のバリューを実践していきたいと思います。
-
弊社バリューである FF memes の1つです。詳しくはこちら: https://recruit.feedforce.jp/ ↩