本記事はソラコムが提供する「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の資料や、動画アーカイブが公開されていますので、ぜひご覧下さい。
この連載の記事
-
第484回
デジタル
AWS re:Invent 2024に見る、IoTの成熟と生成AIとの融合 -
第483回
デジタル
二歳半の子供を持つエンジニアの一日の働き方 -
第482回
デジタル
VPN 対応の産業用 LTE ルーターの価格改定【30%オフ】 -
第481回
デジタル
時間帯に応じたメール通知の構築方法 : SORACOM LTE-M Button と SORACOM Flux の活用 -
第480回
デジタル
SORACOM Flux 料金プランを発表しました -
第479回
デジタル
12/11-13 商業施設・店舗DX展に出展：最新IoTソリューションや事例をご紹介 -
第478回
デジタル
コープさっぽろが、クラウド型カメラ「ソラカメ」を全店舗で導入、現場主導の改善を実現、サーバールームの異常な温度上昇を通知する新規掲載レシピ takuyaのほぼ週刊ソラコム 11/16-11/29 -
第476回
デジタル
WebRTCとMedia over QUIC Transportの性能比較 -
第475回
デジタル
SORACOM Lagoon 3 の [Math] 機能で、複数データを組み合わせた通知の手順 -
第474回
デジタル
SORACOM Flux の AI アクションに Amazon Bedrock – Anthropic Claude 3.5 Haiku を追加、Teltonika RUT240 の価格を改訂 takuyaのほぼ週刊ソラコム 11/02-11/15