Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

SORACOM
October 25, 2021

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

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/

SORACOM

October 25, 2021
Tweet

More Decks by SORACOM

Other Decks in Technology

Transcript

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  11. ドキュメントいっぱいありますよね?

    View full-size slide

  12. ドキュメントいっぱいありますよね?

    View full-size slide

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

    View full-size slide

  14. 名前を大事に

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    ユーザーコンソール
    ユーザー

    View full-size slide

  38. in:#j_glossary has:pin

    View full-size slide

  39. in:#j_glossary has:pin {word}

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide