本記事はソラコムが提供する「SORACOM公式ブログ」に掲載された「テクニカルライティングの第一歩、用語集を作ろう」を再編集したものです。
2021年10月14日に開催された、LINE Technical Writing Meetup vol.8。わかりやすいドキュメントが書きたい、複雑な技術のことを伝えられるようになりたい、そんな技術者向けにテクニカルライターのみなさんが知見を共有する勉強会です。
Meetup前半では、トップバッターとして、LINE株式会社 開発4センター Developer Contentチームで、テクニカルライティングとイラストを担当する米倉 裕基氏が「つたわるイラスト」について発表しました。
「つたわるイラスト」についての米倉氏の講演は、過去のMeetupですでに2回実施された人気コンテンツです。この日のテーマは、黄金比を使ってわかりやすいイラストを描く方法をデモンストレーションを交えて解説しました。
Meetup後半では、ソラコム テクニカルライターの矢崎が登壇し、用語集の作り方についてお話しましたのでレポート形式でご紹介します。
テクニカルライティングにおける用語集の必要性
次に、株式会社ソラコム テクニカルライター 矢崎 誠より、「ドキュメントを改善するためのはじめの一歩」として、社内向けの「用語集」の取り組みを紹介しました。
ソラコムは、通信を軸にIoTプラットフォーム「SORACOM」を提供しています。大企業からスタートアップ、個人のユーザーまで2万を超えるユーザーが、SORACOMを使ってIoTのアイディアを実現しています。
ソラコムには、サービスを紹介するウェブサイトに加え、ユーザーサイトやFAQサイト、IoTシステムの手順を記載したIoTレシピなど数多くのドキュメントが存在します。サポートを担当するCREチームでは、サポート対応に加え、開発ドキュメントの整備もおこなっています。
ドキュメントをわかりやすくするためのアプローチとして「言葉を大事にする」という視点があります。たとえば、SORACOMプラットフォームのはじめ方のページを読んでいくと、アカウント、ユーザー、オペレーターと3つの似た用語が出てきます。それぞれ意味が違うのか、派生語なのか、その意味や使用例をひとつひとつ定義していきます。これらの用語の定義をまとめたものが「用語集」です。
これらの用語は、すでにドキュメントや顧客とのコミュニケーションで使われているため、その用語を利用している人に確認する必要があります。ドキュメント作成に関わるチームメンバーだけではなく、開発に関わったエンジニア、講演などで解説するエバンジェリスト、お客さま向けコンテンツを作るマーケティング担当など、多くの視点から議論することが有効です。
一方、テクニカルライターとしては、これらの用語の定義が決まらないとライティングをはじめられないため、正しい用語を早く決めたいという思いがあります。
一般的に用語集は、表形式で用語とその意味や使用例をまとめていくケースが多くありますが、ソラコムでは、多くの関係者とのスムーズなディスカッション、スピードという二つのニーズを満たすべく、Slack上に「#j_glossary」（用語集）というチャンネルを作成するというアイディアに取り組みました。
用語の定義について、みんなの意見を集める仕組み
Slack上の「#j_glossary」の運用はシンプルです。まず管理者である矢崎が「この言葉とこの言葉の違いは、こういうことですか？」とポストします。すると、いろいろな部署の人から「私はこう考える」「こういう意味で使っていた」というコメントや意見がポストされます。
しばらくの議論を経て、ある程度意見がまとまってきたら、管理者が内容をまとめピン留めします。その後も意見があれば、そのピン留めした用語定義にコメントを加えることもできます。
ピン留めした用語は、管理者がSlack上でピン留めするのみで、スプレッドシートなどにまとめるということはしません。「#j_glossary」で、ピン留めされたポストを一覧化すれば、それが最新の用語集になるという仕組みです。
この仕組みにより、たくさんの意見を反映した上で、今までお客さまとのコミュニケーションで使ってきた用語の意味と齟齬がでないような用語集ができつつあります。開始してわずか3ヶ月間で、30を超える用語の定義が集まりました。
Slack上で用語集を作るメリット
従来の表形式の用語集には、「一度作ったらそれっきり」「用語の使い分けがわかりにくくなりがち」「議論の過程が見えない」「質問があっても質問しにくい」といった課題があったそうです。
しかし、Slack上の用語集の取り組みは、これらの課題を解決しつつあります。
ソラコムでは、普段の社内コミュニケーションはSlack上で行われます。同じコミュニケーション基盤内に用語集を開設すれば、誰もが気になったらすぐに用語集をチェックできます。
検索も簡単で、Slackの検索スペースに「in:#j_glossary has:pin (特定の用語）」 のように入力して検索すれば、正しい定義を検索することができます。
さらにその議論の経緯も簡単に追うことができます。あとから入社した人にとって、A,B,Cという用語があった中で、最終的にAを使うようになった経緯を理解することは、用語を使い分ける際に役に立ちます。
Slack上に最新版の用語集があるからこそ、用語の定義がなければ質問することもできますし、検索して違和感があればコメントをつけて議論を再開することもできます。
矢崎は、もともと「用語集」の作成は、お客さま向けの用語解説を用意するために始まった取り組みだったと説明し、今後はこれらの用語集をお客さま向けに公開することも検討していきたいと講演を締めくくりました。
Meetup動画アーカイブのご案内
Meetupでは、講演後も活発な質疑応答が行われ、テクニカルイラストやライティングの知見が共有されてました。詳細をご覧になりたい方は、Meetupの資料や、動画アーカイブが公開されていますので、ぜひご覧下さい。
この連載の記事
-
第466回
デジタル
カメラとAIで楽器演奏シーンを簡単に残す、IoTプロトタイピングの裏側 -
第465回
デジタル
数千を超えるIoT機器を管理！生成AIで設備運用を効率化するhacomonoの挑戦 -
第464回
デジタル
SORACOMのビジネスパートナープログラムに、新たに5社の認定済パートナーが参画、SORACOM Harvest Data で日時データをタイムスタンプとして利用可能に takuyaのほぼ週刊ソラコム 08/31-09/13 -
第463回
デジタル
SORACOM Lagoon 3 の Alert rule の考え方をマスターして、最適な通知を作成 -
第462回
デジタル
LTE USB ドングル UD-USC1 を SORACOM サービスと組み合わせて利用する -
第461回
デジタル
EV充電インフラを保護する5つの方法 -
第460回
デジタル
IoT プロジェクトの課題を解決する、SORACOM サービスの活用事例 -
第459回
デジタル
ATOM Cam 2 専用 LAN アダプターを販売開始、ソラカメのクラウド録画マルチストリーミング再生機能をリリース takuyaのほぼ週刊ソラコム 08/17-08/30 -
第458回
デジタル
IoTで接続された充電ステーションがEVの普及を促進する -
第457回
デジタル
SORACOM Napterがさらに便利に！リモートアクセスの安全性と利便性を両立したWebターミナルのご紹介