Tweet
Tweet

Slide 1

Slide 1 text

ドキュメントを改善するための はじめの一歩 LINE Technical Writing Meetup vol. 8 2021.10.14

Slide 2

Slide 2 text

自己紹介 • 矢崎 誠 (makoto) • 株式会社ソラコム Technical Writer • テクニカルライター歴: 20数年。もうすぐ25 年って言えそう。前職はLINE株式会社。 • Twitter: @yazakimakoto https://www.amazon.co.jp/dp/4902820102 おすすめの本→

Slide 3

Slide 3 text

株式会社ソラコム 概要 商号 株式会社ソラコム / SORACOM, INC. 代表取締役社長 玉川 憲 事業概要 IoT プラットフォームの提供 拠点 日本、英国、米国(シアトル) 2017年8月に KDDI グループ入り

Slide 4

Slide 4 text

モノやコトをデジタル化 現場を知る、現場を動かす IoT とは？ クラウド センサー/デバイス ネットワーク 現場のモノやコトを デジタル化 現場とクラウドを つなげる 現場のデジタル データを活用

Slide 5

Slide 5 text

IoT デバイス クラウドサービス ü 遠隔操作 ü メンテナンス ü 蓄積・見える化 ü アラート通知 通信 デバイス センサー キット IoT 通信 IoT SIM LPWA パートナー デバイス パートナークラウド (AWS / Microsoft / Google / IBM) Wi-Fi / 有線 (-5& ( -5&. SORACOM は IoT の「つなぐ」を簡単に

Slide 6

Slide 6 text

テレワーク支援や労働力の置き換え 遠隔地のインフラ管理 省エネ・コスト削減 レガシー設備のアップデート あらゆる “モノ” がつながり、社会を変え始めている

Slide 7

Slide 7 text

新たなビジネス創出 農業や漁業のスマート化 既存ビジネスの顧客体験向上 現場と利用者をデジタルでつなぐ あらゆる “モノ” がつながり、社会を変え始めている

Slide 8

Slide 8 text

20000以上のお客様、300万を超える IoT 契約回線 セルラー、Sigfox、LoRaWAN を含む SORACOM Air 総回線数 1回線の検証から 数十万回線のビジネス活用まで 通信回線をクラウドのように

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

ソラコムに入社してみたら思ったより ドキュメントがたくさんありました

Slide 11

Slide 11 text

ドキュメントいっぱいありますよね？

Slide 12

Slide 12 text

ドキュメントいっぱいありますよね？

Slide 13

Slide 13 text

ドキュメントいっぱいありますよね？ どこから手を付ける？

Slide 14

Slide 14 text

名前を大事に

Slide 15

Slide 15 text

名前を大事に LINE Technical Writing Meetup vol.2 より

Slide 16

Slide 16 text

名前を大事に LINE Technical Writing Meetup vol.2 より ソラコムでも名前を大事に

Slide 17

Slide 17 text

ソラコムでも名前を大事に

Slide 18

Slide 18 text

ソラコムでも名前を大事に !?

Slide 19

Slide 19 text

ソラコムでも名前を大事に !?

Slide 20

Slide 20 text

ソラコムでも名前を大事に アカウントなの？ オペレーターなの？

Slide 21

Slide 21 text

ソラコムでも名前を大事に ユーザーかもしれない …？

Slide 22

Slide 22 text

ソラコムでも名前を大事に ユーザーかもしれない …？ 同じものは同じ名前で呼びたい

Slide 23

Slide 23 text

そうだ、用語集 (glossary) を作ろう ただし… • すでにリリースされているサービスの用語のため、7/1入社の自分が勝手に用語 を変更できない。たとえば「オペレーター」と「アカウント」は、ひょっとした ら違うことを指しているのかもしれない。もし同じことを指しているなら 1 つの 用語に揃えたい。 • 今後も用語が揺れているように見えたときに、誰かに聞きたい。(特定の人に軽 く聞くのではなく、なるべく多くの人にちゃんと聞きたい。議論して決めたい) • 正しい用語を早く決めたい。(決まらないと、書くモチベーションがあがらな い。)

Slide 24

Slide 24 text

そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 :

Slide 25

Slide 25 text

そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。

Slide 26

Slide 26 text

そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。 用語の使い分けが わかりにくくなりがち

Slide 27

Slide 27 text

そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。 用語の使い分けが わかりにくくなりがち 議論の過程が見えなくなりがち

Slide 28

Slide 28 text

そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。 用語の使い分けが わかりにくくなりがち 議論の過程が見えなくなりがち 疑問があっても 質問しにくくなりがち

Slide 29

Slide 29 text

そうだ、用語集 (glossary) を作ろう カテゴリ 用語 説明 使用例 SORACOM Mosaic IoT デバイス デバイスに搭載されたセンサーでデータを収集し、そのデー タをそのまま、デバイスに内蔵した通信モジュールを使用し て SORACOM プラットフォームに送信できるデバイスです。 たとえば、SORACOM LTE-M Button シリーズは、IoT デバイス です。 IoT デバイスから基地局・交換局 などの設備までは各通信事業者が 提供し、交換局などの設備と SORACOM プラットフォーム間は 専用線で接続しています。 SORACOM Mosaic エッジコンピューター デバイスに搭載されたリソースでデータを処理したうえで、 デバイスに内蔵した通信モジュールを使用して SORACOM プ ラットフォームに送信できるデバイスです。たとえば、S+ Camera シリーズは、エッジコンピューターです。 SORACOM Mosaic コンソールを使 用すると、エッジコンピューター に AI アルゴリズムをインストール したり、SORACOM プラット フォームへの接続状況を確認でき ます。 : でも、一度作ったらそれっきりに なりがち…。 用語の使い分けが わかりにくくなりがち 議論の過程が見えなくなりがち 疑問があっても 質問しにくくなりがち 用語集を表でまとめても 継続できなそう 🤔

Slide 30

Slide 30 text

#j_glossary

Slide 31

Slide 31 text

Slackに #j_glossary チャンネルを作成 • 一度作ったらそれっきり になりがち • 用語の使い分けがわかり にくくなりがち • 議論の過程が見えなくな りがち • 疑問があっても質問しに くくなりがち

Slide 32

Slide 32 text

Slackに #j_glossary チャンネルを作成 • 用語定義の始まり

Slide 33

Slide 33 text

Slackに #j_glossary チャンネルを作成 • いろいろな人との議論を経て…

Slide 34

Slide 34 text

Slackに #j_glossary チャンネルを作成 • いろいろな人との議論を経て…

Slide 35

Slide 35 text

Slackに #j_glossary チャンネルを作成 • 決まったと思ってピン留め！

Slide 36

Slide 36 text

Slackに #j_glossary チャンネルを作成 • 決まったと思ってピン留めしたけど、さらにコメントが入り…

Slide 37

Slide 37 text

Slackに #j_glossary チャンネルを作成 • 決まったと思ってピン留めしたけど、さらにコメントが入り… いよいよ決定してもう一度ピン留め！

Slide 38

Slide 38 text

エッジコンピューター 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 ユーザーコンソー ル ユーザーコンソール ユーザー

Slide 39

Slide 39 text

in:#j_glossary has:pin

Slide 40

Slide 40 text

in:#j_glossary has:pin {word}

Slide 41

Slide 41 text

FAQ Q) #j_glossaryで議論が終わった後に、ほかの場所に転記します か？ A) いいえ。転記しません。このチャンネルにピン留めして終わ りです。 Slackで行われた議論の内容とか、文例とか、そういったものが 多いほうが、用語の意味や定義を正しく理解し、正しく使えるよ うになることを期待しています。

Slide 42

Slide 42 text

FAQ Q) 誰でもピン留め (用語決定の宣言) をしてもいいですか？ A) いいえ。管理者が追加/削除を管理します。 TCシンポジウム (https://www.jtca.org/symposium/index.html) の研 究発表で、適切に用語集を管理するには、管理者を置くことがと ても大切という発表があったと記憶しています。それに倣って、 管理者を置いています。

Slide 43

Slide 43 text

Slackに #j_glossary チャンネルを作成 • 一度作ったらそれっきり になりがち • 用語の使い分けがわかり にくくなりがち • 議論の過程が見えなくな りがち • 疑問があっても質問しに くくなりがち 全部解決する といいな！

Slide 44

Slide 44 text

ご清聴ありがとうございました！ Twitter: @yazakimakoto