チームの言語化を促進する esa

こんにちは。ディレクターの菊池です。

最近会社の制度を使って、デスク環境に24インチ縦型モニターを追加しました。縦に長いため、議事録や仕様書など「書く仕事」がとても捗ります。

ディレクターに限らず、開発業務はコード以外にも書く仕事がたくさんあります。今回は弊社の書く仕事を助ける「esa」について少し紹介してみたいと思います。

リモートワークにおける課題

弊社はリモートワーク歴が長いため、環境は比較的整備されている方だと思います。前職時代も週3-4程度の在宅勤務は経験していましたが、それでも入社後は「フルリモートでここまでできるのか！」といった感覚がありました。

一方でフルリモートにおける課題ももちろんあり、下記のような点が気になっていました。

• Slack の times への投稿が盛んだが、有益な情報が流れてしまいストック情報化できていなかった
• ある程度まとまった文書を書いて共有する方法が無く、Slack や Asana での往復のやり取りが増えていた
• 非同期コミュニケーション or ウェブ会議の間を埋める方法が無く、無駄な会議が増えてしまっていた

もっと気軽にテキストでまとめて URL でパッと渡せるものがあると良いな〜と考えていたところで、社内システムの見直しタイミング等もあり SaaS 型ドキュメントツールの検討をはじめました。

ドキュメントツールの導入検討

ドキュメントツールの選定は、主に以下を要件としました。

• Markdown で書ける
• メンテナンスコストが低い

Markdown で書ける

Markdown を重視した理由は主に2つあります。

1つ目は慣れた記法で書けるということ。弊社はエンジニアが多い組織のため、当ブログをはじめ様々な箇所で Markdown を使用しています。 独自の記法を覚える必要があるツールはやや導入障壁が高いと判断し、Markdown ベースのツールであることを重視しました。

2つ目はサービス終了時を見据えたもので、やはり会社の資産を預けるもののため、一般的で移管がしやすそうなフォーマットであることを重視しました。

esa はほとんど素の Markdown で書けて、UML や mermaid にも対応しています。 Git ブランチ図なども書けるのはなかなか推せるポイントです。

メンテナンスコストが低い

メンテナンスコストが低いことも重視しました。より正確には「あまり慎重にならなくても使える」ということです。

我々が欲しかったのは「気軽に書いて社内共有できるツール」だったので、書く度に「どこに書こうか」「書き方は合っているか」などに気を遣うツールは避けたいと考えていました。

この点でも esa は優れていて、シンプルなディレクトリ構造 + Markdown ドキュメントの集合体なので、最上位のディレクトリだけはじめに作ってしまえば十分に機能します。 ディレクトリごとまるっと動かしたりも簡単にできるため、書きはじめる障壁がグッと下がります。

その他もちろん費用面なども選定基準には入りましたが、主にこれら2つをポイントに esa を採用しました。

esa に何を書いているのか

導入から1年半ほどが経過し、今では毎日何かしらが esa に更新され続けています。主な利用ケースを紹介します。

業務日報を書く

フルリモートだとそれぞれが何をやっているのか分からりづらいため、終業時に今日やったことや学んだことを簡単にまとめて共有しています。 これはフロー情報のため esa への記載は強制していませんが、テンプレート機能が便利なため今でも一部のメンバーはこの日報作成に esa を利用しています。

技術メモを書き留める

シンプルに課題、要因、解決方法、参照のような見出しを持つテンプレートを用意し、開発上詰まった点とその解決方法を esa に書き留めています。 プロジェクト間で共通でぶつかりがちな問題はだいぶドキュメンテーションが進んできて、段々と「ググる前にまず esa る」が標準になってきました。

Drupal モジュール情報を書く

Drupal 開発においてモジュールの引き出しはとても重要で、どんなモジュールがあって何ができるかが頭に入っていないと適切なソリューション提供ができません。

もちろん経験と共に身に付けていく部分ではありますが、一人だと限界があるためモジュール知識を社内で共有し積み上げるようにしています。 気になるモジュールを見つけたらとりあえずちょっと触って esa に書く文化ができてきました。

下記は PDFPreview モジュールの例ですが、シンプルにそのモジュールが何かと基本的な使い方等をまとめています。

よく使う設定やコードスニペット

おそらく一番見られているページはこれで、Drupal における settings.php, settings.local.php, services.local.yml 等でよく使う記述がスニペットとしてまとめられています。

シンタックスハイライトも効きクリップボードへ保存もできるため、よく使うコードをスニペットとして保存していく用途にもおすすめです。

[番外編] モニターの要件定義

冒頭で紹介した縦型モニター購入時にも、まず esa に困っていることや欲しいモニターの要件を書いて意見を募りました。 esa 公式でも言及されている通り、不完全でも書き出して更新しながら情報を育てていける点が弊社の文化とよくマッチしているようです。

まとめ

今回はライトに書けるドキュメントツール esa を紹介しました。 Markdown + ディレクトリ構造のシンプルで書きやすいドキュメントツールを探している方にはおすすめです。

着実にメンバーの言語化能力も向上している気がするので、引き続き当ブログもよろしくお願いいたします！