読者です 読者をやめる 読者になる 読者になる

てくすた

ピクスタ株式会社のエンジニア・デザイナーがつづるよもやまテクニカルブログです

esaの話をしよう

ドキュメント

10年の複雑

開発部の総務みたいな存在のさとうといいます。
得意技は床下のケーブリングです。

PIXTAは来年、最初のサイトリリースから10周年を迎えます。サービスが始まって9年、10年と経つと相当のナレッジが溜まるのですが、そうなると管理が大変なことになります。業務知識・サービスの概要・構成管理・手順書・設計・議事録など、ドキュメントをどこかにわかりやすい形でおいておきたいものですが、これまではどのように管理していくのか方針やルールが定まっていませんでした。

そんな状況だったので、ピクスタでは「esa」というサービスに集約することにしました。

esaについては検索するだけでもたくさんのレビューエントリが見つかるのですが、今回はそのドキュメントを管理するためのサービスesaをピクスタでどのように使っているかご紹介したいと思います。中の人は先日東京ビッグサイトで開催されたYAPC::Asia 2015に登壇されていたのでそれも要チェックです。

ドキュメントを管理するためのツール選定

当時、ドキュメントを管理するためのサービスは他にも存在していました。

エンジニアが主体となって使うことを想定していたため、Wordのような「文書」を書くのとはちょっと違うな、という感覚がありました。 要件はたくさんあるのですが、主には次のようなものです。

  • 運用コストがかからない
  • MarkDownで書きたい
  • シンタックスハイライトは必須
  • 誰が書いたかわかるようにしたい
  • 版管理したい
  • コメントが付けられる
  • 「いいね」機能
  • どこに何があるかわかる
  • 書きやすさ

‥というような要件をすべて満たすものはないか、という観点でトライアルをやってみて行き着いたサービスが「esa」でした。それ以前に作っていたドキュメントは幸いどこもエクスポート(アーカイブという名前だったりもします)機能がついていて、シームレスに移行することが出来ました*1

「esa」のよさ

使いやすさ

ユーザビリティを定量的に測るというのは難しいと思うのですが、書きやすさが一番あるサービスだという点は強調しておきたいと思います(もちろん個人の感想によるものですから異論はあるでしょうが)。

書きやすさは書くためのモチベーションに直結するため、重要な要素だと判断しました。カテゴリがツリー状になっていてドキュメントがその横に表示されるというのも、エクスプローラやFinderに似ていて理解が早く使いやすいと感じるのだと思っています。

image.png (53.7 kB)

サポートのこと

これはこの先どのようになるのか未知数なところですが、Twitterの #esa_io などで積極的に見てくれているのと、フィードバックに対するレスポンスは感心するほど早いです。ユースケースの説明は必要になるのですが、「こういう機能があったらいいのにな」というフィードバックを送信する敷居が下がることにも繋がるのかなと思います*2。実際、ぼくらが「あっこれあったらな」と思ってリクエストした機能が実装されたこともありました。あれは嬉しいですね。

ピクスタで書かれているもの

ゆるく言うと、こんなかんじです。

  • 日報
  • ポエム
  • テクニカルノート
  • 仕様書き
  • イベントの振り返り

特に制限はしていないので、プライバシーや機密や関わることや公序良俗に反することでなければ各個人が自由に書いています。イベントや勉強会に参加したメンバーのレポートを書いていることもありますし、コードスニペットにしていたり、良記事についてはコメントやStar(いいね機能)がついたりと盛り上がってきました。

image.png (46.4 kB)

業務知識についての共有はなかなかドキュメントに落ちてこないことがあったのですが、esaに集約したことで「あれこれどうなってんだっけ」のような疑問が解消されることにもつながっています。

使っている人

これは未だにためらってしまうところはあるのですが‥

全社で全員アカウントを持って読み書きできるようにしておくのが望ましいかなと思っています。「書かない人がいるとコスト的に無駄じゃない?」という意見も当然あるのですが、アカウントがあっていつでもアウトプットできる環境があるという前提は書くことの敷居を下げるものだと思います。

導入するころはそんなふうに考えていたのですが、「書かない人は書かないけど、たまに書いた時のうれしさよ」という話を聞いて、妙に背中を押されたような気持ちになりました。

他のツールとの棲み分けについてですが、esaには権限設定の機能はありませんので、シンプルにドキュメントを作って共有する場合はesaへ、権限設定が必要な場合や議事録をリアルタイムに書く場合はGoogleDocsなりOffice365なり、アカウント管理と権限設定ができるサービスを使うほうがよいと考えています。

まとめ

当初はドキュメント管理という観点はあまりなく、どちらかと言うと「自分たちの知っている情報を共有する」ということや「コミュニケーションの促進」が主眼でした。共有することについて、初稿であればメールで配信されるようにしているので、アカウントを持っていない人たちにも共有できることを考えると、組織内は網羅できたのではないかと思っています(しかも、自分たちが思っている以上に見られている)。

運用を続けてみると、共有した後に埋もれないようにするとか、いつだれが書いたかわからないようにしたいとか、量のあるドキュメントをすぐ探せるように管理するには、という事などに目が向けられるようになってきています。

最後に、書いていて書きにくさを感じないツールというのは重要だと思います。エディタ戦争になるくらい議論してみてもよいのではないでしょうか。

皆さんはドキュメント管理、どうしてますか?

*1:JSONで出力したものからのインポートだったので、それをパースしてesa APIにポストするためのツールは別で作る必要がありました。

*2:参考:ユーザーに「フィードバックをしたい」と思わせる、たったひとつの方法 (( ⁰⊖⁰)/) - えいのうにっき