こんにちは。カスタマーリライアビリティエンジニア (Customer Reliability Engineer, CRE) の kaoru です。
これまで dev.soracom.io で提供していたソラコムユーザーのみなさま向けの公式ドキュメント (ユーザーサイト) を users.soracom.io としてリニューアルしましたのでお知らせします。
3 つの改善 — (1) 文書の分類見直し、(2) 検索機能の追加、(3) モバイルデバイスへの対応 — によって SORACOM プラットフォームや各種リファレンスデバイスを使いこなす方法などがより分かりやすく、探しやすく、見やすくなりました。
リニューアルの背景
2015 年 9 月 30 日にサービスを開始して以降、ソラコムをご利用いただいているユーザー向けの文書を dev.soracom.io で提供していました。
その後ユーザーのみなさまのご支援とフィードバックをいただいて、プラットフォームの機能と取り扱うデバイスを拡大してきました。
- セルラーだけでなく Sigfox などを含む 6 つのコネクティビティー、セキュアな IoT / M2M システムの構築を支援する各種ネットワークサービス、データ転送・活用とデバイス管理を支援するアプリケーション連携サービスからなる 合計 18 のサービス群 (100 回を越える機能追加)
- Wio LTE JP Version / Wio 3G SORACOM Edition / M5Stack 用 3G 拡張ボード などの各種開発ボード、SORACOM LTE-M Button シリーズ (powered by AWS / for Enterprise / Plus)、GPS マルチユニット SORACOM Edition、ビーコン対応 GPS トラッカー GW などのリファレンスデバイス、そして遠隔から AI アルゴリズムが書き換え可能なエッジ AI カメラ S+ Camera Basic
- SORACOM Onyx LTE USB ドングル などの USB 型データ通信端末
その結果として多くの文書が dev.soracom.io に追加され以下のような課題が見えてきていました。
- SORACOM のご利用者層の拡大により、開発者だけでなく IoT で手軽にデジタル化に取り組もうとされる方への「ガイド」が求められるようになってきた。
- 検索機能が無いため、自分が必要としている情報をタイトルから推測したり、検索エンジンの使い方を工夫して探し出す必要があった。
- モバイルデバイスからの閲覧に最適化されていないため、スマートフォンやタブレットでユーザーサイトを参照しながらの操作したいというお声に対応できていなかった。
振り返ってみると、SORACOM そのもののリリース直後は以下のようにとてもシンプルなサイトでした。
ここから 2021 年 3 月までの文書数の推移をグラフ化したものがこちらです。
このグラフは SORACOM プラットフォームの進化の歴史と言えます。徐々にペースが向上していますが、これは文書作成にエンジニアや CRE だけでなく、ソリューションアーキテクト、エバンジェリストといったメンバーも関わることで、1 つでも多くの情報を提供していきたいという姿勢の表れとなっています。
そして 2021 年 3 月 23 日時点のスクリーンショットがこちらです。文書数が大幅に増加していることがお分かりいただけます。
ヘッドライン部分が < for Developers /> から < for SORACOM Users /> へと変わっていることにお気づきでしょうか。これは、一例を挙げると SORACOM LTE-M Button ボタンのクリックをメールで通知する 機能のように、開発者でなくとも SORACOM をご利用いただけるようになってきたことを受けて、SORACOM を利用するすべての方、すなわち「ユーザー」に向けたサイトという意味を込めて 2020 年夏に改称したものです。
こうした変化の中、増え続ける文書を快適に閲覧いただくために、サイト内検索やスマートフォン / タブレットへの対応といった機能面の充実が急務となってきたわけです。
新しいユーザーサイトの改善ポイント
ソラコムの CRE チームは、お客様自身で疑問点を解決できる仕組みを整え、お客様が私たちにお問い合わせすることなく SORACOM のサービスを使いこなしていただくことを目指して活動しています(CRE チームの目標や活動は こちらの記事 もご参照ください)。この活動の一環として上記の課題を解決する 3 つの改善を行いました。
文書の分類見直し
文書の目的と内容によって以下の 4 つのカテゴリに分類し直しました。
- ガイド: SORACOM を使い始めていただく方へのガイドとなる文書—SORACOM はじめの一歩、最近 PDF 版を公開した経理・購買部門ご担当者様向けガイドの Web 版、IoT システムのデザインパターン、IoT デバイスやスターターキット商品、開発ボードの使い方など
- ドキュメント: SORACOM を使いこなしていただくための文書—SORACOM プラットフォームサービスと共通機能の詳細情報
- リソース: アイコンセットや SDK といった各種リソース
- 開発者向けツール: API リファレンスや CLI など開発者をターゲットとした情報
同一カテゴリの文書は、できるだけセクションも統一し構造を把握しやすくしています。
検索機能の追加
SORACOM 公式ブログ と同じ Algolia による検索機能を追加しました。ページ上部のテキストボックスと、独立した 検索ページ からご利用いただけます。
検索結果は上記のカテゴリ毎に絞り込みできます。ユーザーサイトだけでなくサポートサイトで提供している FAQ の内容を同時に検索できます。検索結果は今後改善していきます。
モバイルデバイスへの対応
利用者の画面サイズに応じて適切にコンテンツが読めるよう改善しました。これまではデスクトップ PC からのご利用を想定したレイアウトになっていましたが、これからはスマートフォンやタブレットでユーザーサイトを参照しながらの設定がやりやすくなりました。
オープンソースではなくソラコムでの使用のみに限定されたライブラリではありますが、Soracom Design System でどのようなコンポーネントやデザインがあるか公開しています。ぜひご覧ください。
利用方法
以下の URL からどなたでも無料でご覧いただけます。
dev.soracom.io/jp/ でホストしていた情報はすべて移行しており、旧 URL へアクセスした場合は該当する新しいページへリダイレクトされます。分類の見直しと整理に伴いパス部分は大きく変更されています。
おわりに
「よく設計された製品やサービスはドキュメントが不要である」という言葉があります。たしかに、私たちが普段使っているスマートフォンやネット上のサービスは、ドキュメントを読まずとも使えているのではないでしょうか。
ではドキュメントが不要かというと、そんなことは無いと考えています。たとえば私が利用している動画サービスには「データ節約モード」があることをマニュアルで知り、設定してみたところ映像品質をほとんど落とさずに通信量を削減できました。このように、ドキュメントから新たな発見が得られるわけです。
SORACOM は 1 日単位でのご契約が可能な IoT 向けデータ通信という手軽さを背景に、15,000 を超えるお客様にご利用いただけるまでに成長してきましたが、これは SORACOM プラットフォームのほんの一部に過ぎません。検証から本番、スタートアップから大企業とさまざまなユースケースをカバーする機能があるのが SORACOM プラットフォームです。
たとえば私の好きな バイナリパーサー は、通信量・通信費用を削減しデバイスの消費電力を下げることが期待できます(参考: バイナリによるデータフォーマットの重要性)。IoT 向けのプラットフォームだからこその機能ではないでしょうか。IoT プロジェクトの実施にあたって困ったときは、ユーザーサイトを読んでいただくと何かしらの発見やヒントを得られるかもしれません。検索機能とあわせて使いこなしていただけると嬉しいです。
私たちは、SORACOM プラットフォームが提供する価値を皆さまご自身で発見・活用いただくために、このユーザーサイトがとても重要と考えています。今回のリニューアルでは主に構造・インフラ・デザインの改修にフォーカスし、今後の(肝⼼の)内容のアップデートに向けた礎が整備できました。より分かりやすく、探しやすく、見やすくを目標に改善を続けていきます。
一緒にユーザーサイトを成長させていく仲間を募集しています
お客様の成功のために、技術文書を作成しそれを支えるプラットフォームを構築・維持していく仲間を募集しています！詳しくは以下のページをご覧ください。募集職種やオープンハウスのスケジュールを掲載していますので、定期的なチェックをいただけるとありがたいです。
― ソラコム CRE チーム mick (三國)、kanu (加納)、kaoru (佐藤)