本記事はソラコムが提供する「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の資料や、動画アーカイブが公開されていますので、ぜひご覧下さい。
この連載の記事
-
第397回
デジタル
Make a Global Impact as a Technical Writer at Soracom -
第396回
デジタル
SORACOM LTE-M Button powered by AWSの移行受付を開始、SPSアワード 2023の表彰を発表 takuyaのほぼ週刊ソラコム 04/01-04/14 -
第395回
デジタル
SORACOMの新機能開発の舞台裏 ― お客様の声からリリースまでの道のり -
第394回
デジタル
動画で分かる！SORACOM Lagoon 3への移行の手順 -
第393回
デジタル
ソラカメ運用管理をより簡単に！アクセス権限設定テンプレートのご紹介 -
第392回
デジタル
生成AIによる「ブログの原稿作り」手順やプロンプトを公開 -
第391回
デジタル
クラウド型カメラの実機を見ながら相談できる「ソラカメ デモルーム」 -
第390回
デジタル
SORACOM Lagoon 2 から Lagoon 3 への移行に関する、よくある 9 の質問にお答えします -
第389回
デジタル
スイングバイIPOにて、ソラコム本日上場 -
第388回
デジタル
IoTのセンサーやデバイスの選び方・活かし方とは？ ― 2/29セミナーレポート