今年に入ってから自社製品向けのオンラインドキュメントを改善していくのを本格化しようと思い、自社製品向けの Sphinx テーマを開発しています。
自社でオンラインドキュメントツールに投資するというのはあまりないと思うので、その話を雑に書いていきます。
なぜドキュメントなのか
実際、ドキュメントツールに投資する話はほとんど聞かないと思います。自社でも「やっと投資できるような状況になった」というのが正しいです。
今まではなんとか自社製品で利益を出すというのが目標だったのですが、ありがたいことに、自社製品の売り上げで会社が回るようになってきました。そこで投資先を考えた結果、「既存のお客様が頻繁に利用するドキュメントを便利にする」ということにしました。
ドキュメントが使いづらいというのはとてもストレスを感じます。特に弊社製品はミドルウェアやその SDK という事もあり、ドキュメントありきです。ドキュメントが使いづらいということは自社製品が使いづらいということになるからです。
なぜ Sphinx なのか
もともと Sphinx を使っていた理由は、自分が reStructuredText (rst) に慣れていたというのが理由です。Python を利用していたこともあり、Sphinx を使う前から rst に慣れ親しんでいました。
もちろん Sphinx 以外のオンラインドキュメントツール（サービスを含む）も検討しました。
ただ、決め手としてはラムダノートの鹿野さんから「オンラインドキュメントであれば Sphinx 一択だと思う、特に rst に慣れているなら」というアドバイスを頂いたのが決め手でした。
また自前でホスティングしたいというのもありました。その点 Sphinx は Netlify との相性が良く、気軽にデプロイできます。
既存の Sphinx テーマへの不満
現時点では Read the Docs の Sphinx テーマを利用していますが、いくつか課題があります。
- デザインやレイアウトが好きではない
- 日本語との相性が悪い
そのため、自分たちにとって使いやすい Sphinx テーマを用意することにしました。
Sphinx コミッター小宮さんの招聘
残念ながら社内には Sphinx に詳しい社員はいません。そのため専門家のアドバイスが欲しいと思ったときに目を付けたのが「プラチナスポンサー」です。
時雨堂は Sphinx コミッター小宮さんのプラチナスポンサーです。このスポンサー特典として小宮さんの「答えられる範囲」で Sphinx のアドバイスがもらえるというのがあります。
小宮さんに弊社 Slack に参加頂き Sphinx テーマ開発時に Sphinx のアドバイスをしてもらえないか打診したところ快諾頂きました。
Sphinx テーマ作り
フロントエンドを普段担当している社員にお願いすることにしました。小宮さんとも面識があり（むしろ元同僚）、連携に困らないと思ったからです。
社員にお願いしたことは以下の通りです。
- 3 ペインレイアウトにして欲しい
- 日本語が読みやすくして欲しい
- 時雨堂のテーマカラーにして欲しい
- 検索に Algolia が使えるようにして欲しい
- rebar3 のドキュメントのような感じがいい
- Apache License 2.0 でオープンソースとして公開できるようにして欲しい
- 将来的に Algolia の検索部分は拡張として外に出してオープンソースとして公開して欲しい
検索機能
Sphinx の検索機能は残念ながら頑張れてるとは言えないと思います。そこで検索サービスを組み込むことにしました。ここは費用を払っても問題ないと判断しました。
いろいろドキュメント検索サービスを調べましたが、 readme.com が採用している Algolia が日本語にも対応しておりかなりよさそうと判断しました。
Algolia を Sphinx テーマに組み込む事で、検索が便利になるだろうと判断しました。
公開に向けて
現在テーマを少しずつ作成中です。特に隠すことはないのですでにオープンソースとして GitHub に公開しています。
小宮さんからは「この仕組みを実現したい場合は、何をすべきか」という的確なアドバイスをもらえており、本当に助けられています。
検索機能を統合したら、まずは開発版や SDK 向けのドキュメントに当てていく予定です。
まったりとお待ちください。ノウハウ自体は全て公開していく予定です。
ちなみに、修正自体は小宮さんが行っていますが、 Sphinx 側にもフィードバックを少しですができています。
