ドキュメントを改善するためのはじめの一歩

LINE TECHNICAL WRINTING MEETUP Vol.8
2021.10.14
https://line.connpass.com/event/226589/

「ドキュメントを改善するためのはじめの一歩」
株式会社ソラコム
テクニカルライター
矢崎 誠

イベントレポート
https://blog.soracom.com/ja-jp/2021/10/25/technical_writing_tips_slack_glossary/

Transcript

1. ドキュメントを改善するための はじめの一歩 LINE Technical Writing Meetup vol. 8 2021.10.14
2. 自己紹介 • 矢崎 誠 (makoto) • 株式会社ソラコム Technical Writer • テクニカルライター歴: 20数年。もうすぐ25 年って言えそう。前職はLINE株式会社。 • Twitter: @yazakimakoto https://www.amazon.co.jp/dp/4902820102 おすすめの本→
3. 株式会社ソラコム 概要 商号 株式会社ソラコム / SORACOM, INC. 代表取締役社長 玉川 憲 事業概要 IoT プラットフォームの提供 拠点 日本、英国、米国(シアトル) 2017年8月に KDDI グループ入り
4. モノやコトをデジタル化 現場を知る、現場を動かす IoT とは？ クラウド センサー/デバイス ネットワーク 現場のモノやコトを デジタル化 現場とクラウドを つなげる 現場のデジタル データを活用
5. IoT デバイス クラウドサービス ü 遠隔操作 ü メンテナンス ü 蓄積・見える化 ü アラート通知 通信 デバイス センサー キット IoT 通信 IoT SIM LPWA パートナー デバイス パートナークラウド (AWS / Microsoft / Google / IBM) Wi-Fi / 有線 (
   
   -5&
   
   ( -5&. SORACOM は IoT の「つなぐ」を簡単に
6. テレワーク支援や労働力の置き換え 遠隔地のインフラ管理 省エネ・コスト削減 レガシー設備のアップデート あらゆる “モノ” がつながり、社会を変え始めている
7. 新たなビジネス創出 農業や漁業のスマート化 既存ビジネスの顧客体験向上 現場と利用者をデジタルでつなぐ あらゆる “モノ” がつながり、社会を変え始めている
8. 20000以上のお客様、300万を超える IoT 契約回線 セルラー、Sigfox、LoRaWAN を含む SORACOM Air 総回線数 1回線の検証から 数十万回線のビジネス活用まで 通信回線をクラウドのように
9. ドキュメントを改善するための はじめの一歩
10. ソラコムに入社してみたら思ったより ドキュメントがたくさんありました
11. ドキュメントいっぱいありますよね？
12. ドキュメントいっぱいありますよね？
13. ドキュメントいっぱいありますよね？ どこから手を付ける？
14. 名前を大事に
15. 名前を大事に LINE Technical Writing Meetup vol.2 より
16. 名前を大事に LINE Technical Writing Meetup vol.2 より ソラコムでも名前を大事に
17. ソラコムでも名前を大事に
18. ソラコムでも名前を大事に !?
19. ソラコムでも名前を大事に !?
20. ソラコムでも名前を大事に アカウントなの？ オペレーターなの？
21. ソラコムでも名前を大事に ユーザーかもしれない …？
22. ソラコムでも名前を大事に ユーザーかもしれない …？ 同じものは同じ名前で呼びたい
23. そうだ、用語集 (glossary) を作ろう ただし… • すでにリリースされているサービスの用語のため、7/1入社の自分が勝手に用語 を変更できない。たとえば「オペレーター」と「アカウント」は、ひょっとした ら違うことを指しているのかもしれない。もし同じことを指しているなら 1 つの 用語に揃えたい。 • 今後も用語が揺れているように見えたときに、誰かに聞きたい。(特定の人に軽 く聞くのではなく、なるべく多くの人にちゃんと聞きたい。議論して決めたい) • 正しい用語を早く決めたい。(決まらないと、書くモチベーションがあがらな い。)
24. そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 :
25. そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。
26. そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。 用語の使い分けが わかりにくくなりがち
27. そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。 用語の使い分けが わかりにくくなりがち 議論の過程が見えなくなりがち
28. そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。 用語の使い分けが わかりにくくなりがち 議論の過程が見えなくなりがち 疑問があっても 質問しにくくなりがち
29. そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。 用語の使い分けが わかりにくくなりがち 議論の過程が見えなくなりがち 疑問があっても 質問しにくくなりがち 用語集を表でまとめても 継続できなそう 🤔
30. #j_glossary
31. Slackに #j_glossary チャンネルを作成 • 一度作ったらそれっきり になりがち • 用語の使い分けがわかり にくくなりがち • 議論の過程が見えなくな りがち • 疑問があっても質問しに くくなりがち
32. Slackに #j_glossary チャンネルを作成 • 用語定義の始まり
33. Slackに #j_glossary チャンネルを作成 • いろいろな人との議論を経て…
34. Slackに #j_glossary チャンネルを作成 • いろいろな人との議論を経て…
35. Slackに #j_glossary チャンネルを作成 • 決まったと思ってピン留め！
36. Slackに #j_glossary チャンネルを作成 • 決まったと思ってピン留めしたけど、さらにコメントが入り…
37. Slackに #j_glossary チャンネルを作成 • 決まったと思ってピン留めしたけど、さらにコメントが入り… いよいよ決定してもう一度ピン留め！
38. エッジコンピューター IoT デバイス オペレーター ルートユーザー SAM ユーザー API キー API トーク ン UNIX 時間 (ミリ 秒) B KiB Mi B GiB SORACOM ソラコム オペレーター ID セッション 無線リンク SORACOM API リファレンス SIM グルー プ LoRa グループ Sigfox グループ シングルクリック ダブルクリック ⻑押し セッション状態 SORACOM サポートサイ ト SORACOM プラットフォーム SORACOM Air for セル ラー SORACOM Status Dashboard SORACOM ユーザーコンソー ル ユーザーコンソール ユーザー
39. in:#j_glossary has:pin
40. in:#j_glossary has:pin {word}
41. FAQ Q) #j_glossaryで議論が終わった後に、ほかの場所に転記します か？ A) いいえ。転記しません。このチャンネルにピン留めして終わ りです。 Slackで行われた議論の内容とか、文例とか、そういったものが 多いほうが、用語の意味や定義を正しく理解し、正しく使えるよ うになることを期待しています。
42. FAQ Q) 誰でもピン留め (用語決定の宣言) をしてもいいですか？ A) いいえ。管理者が追加/削除を管理します。 TCシンポジウム (https://www.jtca.org/symposium/index.html) の研 究発表で、適切に用語集を管理するには、管理者を置くことがと ても大切という発表があったと記憶しています。それに倣って、 管理者を置いています。
43. Slackに #j_glossary チャンネルを作成 • 一度作ったらそれっきり になりがち • 用語の使い分けがわかり にくくなりがち • 議論の過程が見えなくな りがち • 疑問があっても質問しに くくなりがち 全部解決する といいな！
44. ご清聴ありがとうございました！ Twitter: @yazakimakoto