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

LINE Technical Writing Meetup vol.14

SORACOM
July 26, 2022

LINE Technical Writing Meetup vol.14

2022年7月14日開催

テクニカルライティングをテーマにした技術者向けのミートアップ
LINE Technical Writing Meetup vol. 14

書きやすい文書 / 探しやすい文書を書くコツ
株式会社ソラコム
テクニカルライター
矢崎 誠

SORACOM

July 26, 2022
Tweet

More Decks by SORACOM

Other Decks in Business

Transcript

  1. 書きやすい文書 / 探しやすい文書を
    書くコツ

    View full-size slide

  2. 自己紹介
    • 矢崎 誠 (makoto)
    • 株式会社ソラコム Technical Writer
    • テクニカルライター歴: 約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 とは?
    メーター
    (ガス・電気)
    温度計
    デジタル化
    {
    "gas_volume": 426.807,
    "temperature": 30
    }
    {
    "air_conditioner": true,
    "target_temperature": 28
    }
    遠隔操作
    エアコン
    クラウド
    自宅

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  7. 書きやすい文書 / 探しやすい文書を
    書くコツ

    View full-size slide

  8. わかりやすい文章を書くコツは
    ⾃分が書いた⽂章にうまくたどり着けた⼈に、正しく意図を伝
    えるためのコツ

    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. (コツ 1) ユーザーが知っている
    ことを目次に出す

    View full-size slide

  14. https://soracom.jp/store/20834/

    View full-size slide

  15. https://soracom.jp/store/20834/

    View full-size slide

  16. 読者は必要な情報をどうやって見つけるの?
    ⼀般的には⽬次を眺めます。

    View full-size slide

  17. 読者は必要な情報をどうやって見つけるの?
    ⼀般的には⽬次を眺めます。
    頑張っていい⽬次を作りま
    しょう。

    View full-size slide

  18. 読者は必要な情報をどうやって見つけるの?
    ⼀般的には⽬次を眺めます。
    頑張っていい⽬次を作りま
    しょう。
    いい目次とは?

    View full-size slide

  19. 読者は必要な情報をどうやって見つけるの?
    ⼀般的には⽬次を眺めます。
    頑張っていい⽬次を作りま
    しょう。
    いい目次とは?
    どんな⽬次にすると、
    必要な情報を⾒つけられる
    いい⽬次になる?

    View full-size slide

  20. • ATOM アプリの初期設定を
    する
    • 通知を確認する
    • ATOM Cam 2 を管理する
    • イベントを確認する
    • アカウントを管理する
    良くない例: 画面に表示されている内容をそ
    のまま目次に出す

    View full-size slide

  21. • ATOM アプリの初期設定を
    する
    • 通知を確認する
    • ATOM Cam 2 を管理する
    • イベントを確認する
    • アカウントを管理する
    良くない例: 画面に表示されている内容をそ
    のまま目次に出す

    View full-size slide

  22. • ATOM アプリの初期設定を
    する
    • 通知を確認する
    • ATOM Cam 2 を管理する
    • イベントを確認する
    • アカウントを管理する
    良くない例: 画面に表示されている内容をそ
    のまま目次に出す

    View full-size slide

  23. • ATOM アプリの初期設定を
    する
    • 通知を確認する
    • ATOM Cam 2 を管理する
    • イベントを確認する
    • アカウントを管理する
    良くない例: 画面に表示されている内容をそ
    のまま目次に出す
    開発者ができると思っていることを⽬
    次に出すと
    「わかりにくい!」となりがち

    View full-size slide

  24. ユーザーが知っていることを目次に出す
    ソラカメが「動画をクラウ
    ドに保存するサービス」と
    分かって買っている。
    「動画をクラウドに保存す
    る」ことが書いてありそう
    なタイトルを⽤意する。

    View full-size slide

  25. • カメラを設置する必要がある
    • スマホアプリが必要そう
    • リアルタイム監視に使えそう
    • 録画された映像を⾒られそう
    • モーション検知できそう
    ユーザーが知っていることを目次に出す
    https://soracom.jp/store/20834/

    View full-size slide

  26. • カメラを設置する必要がある
    • スマホアプリが必要そう
    • リアルタイム監視に使えそう
    • 録画された映像を⾒られそう
    • モーション検知できそう
    ユーザーが知っていることを目次に出す

    View full-size slide

  27. • カメラを設置する必要がある
    • スマホアプリが必要そう
    • リアルタイム監視に使えそう
    • 録画された映像を⾒られそう
    • モーション検知できそう
    ユーザーが知っていることを目次に出す

    View full-size slide

  28. • カメラを設置する必要がある
    • スマホアプリが必要そう
    • リアルタイム監視に使えそう
    • 録画された映像を⾒られそう
    • モーション検知できそう
    ユーザーが知っていることを目次に出す

    View full-size slide

  29. • カメラを設置する必要がある
    • スマホアプリが必要そう
    • リアルタイム監視に使えそう
    • 録画された映像を⾒られそう
    • モーション検知できそう
    ユーザーができると思っていることを目次に
    出す
    ユーザーが知っていることを⽬次に出
    すと「わかりやすい!」となりがち

    View full-size slide

  30. • カメラを設置する必要がある
    • スマホアプリが必要そう
    • リアルタイム監視に使えそう
    • 録画された映像を⾒られそう
    • モーション検知できそう
    ユーザーができると思っていることを目次に
    出す
    ユーザーが知っていることを⽬次に出
    すと「わかりやすい!」となりがち
    これがよく⾔われる「ユーザーの立場
    になって考える」だと思います

    View full-size slide

  31. • ATOM アプリの初期設定
    をする
    • 通知を確認する
    • ATOM Cam 2 を管理す

    • イベントを確認する
    • アカウントを管理する
    ユーザーが知っていることを目次に出す

    View full-size slide

  32. • カメラを設置する必要がある
    • スマホアプリが必要そう
    • リアルタイム監視に使えそう
    • 録画された映像を⾒られそう
    • モーション検知できそう
    ユーザーができると思っていることを目次に
    出す
    ユーザーができると思っていることを
    ⽬次に出すと
    「わかりやすい!」となりがち
    これがよく⾔われる「ユーザーの立場
    になって考える」だと思います
    ユーザーが知っていることを⽬次に出
    すと「わかりやすい!」となりがち
    開発者が知っていることを⽬次に出す
    と「わかりにくい!」となりがち
    まとめ

    View full-size slide

  33. • カメラを設置する必要がある
    • スマホアプリが必要そう
    • リアルタイム監視に使えそう
    • 録画された映像を⾒られそう
    • モーション検知できそう
    ユーザーができると思っていることを目次に
    出す
    ユーザーができると思っていることを
    ⽬次に出すと
    「わかりやすい!」となりがち
    これがよく⾔われる「ユーザーの立場
    になって考える」だと思います
    相手が知っていることをベースに説明す
    ると「わかりやすい!」となりがち
    あなたが知っていることをベースに説明
    すると「わかりにくい!」となりがち
    どんなときも一緒です(たぶん)
    ドキュメント以外の場⾯では私も苦⼿です。すみません。。。

    View full-size slide

  34. (コツ 2) そこに無いから無いですね
    という原則を忘れない

    View full-size slide

  35. 良くない例: 同じ内容がいろいろなところに
    書いてある
    「⽀払⽅法を設定する操作」が
    数か所に書かれているとします。
    どこか1か所にたどり着いた⼈は、
    ほかのところに似たようなこと
    が書いてないと考えがちです。
    ⾒つけたページに書いていない
    なら「どこにも説明がない」と
    判断しがちです。

    View full-size slide

  36. 良くない例: 同じ内容がいろいろなところに
    書いてある
    たとえば…

    View full-size slide

  37. 良くない例: 同じ内容がいろいろなところに
    書いてある
    たとえば…
    そこに無いから無いですね

    View full-size slide

  38. 良くない例: 同じ内容がいろいろなところに
    書いてある
    たとえば…
    そこに無いから無いですね
    同じ情報が数か所に書いてあるのに、
    ある情報は1か所にだけ書いてある
    どこにたどり着いても
    必要な情報を得られるように

    View full-size slide

  39. 解決策1:参照 (リンク) を使う

    View full-size slide

  40. 解決策2:参照 (リンク) を使う
    同じ情報が数か所に書いてあるのに、
    ある情報は1か所にだけ書いてある
    必要な情報が書いてあるところを参
    照できるようになっている
    どこにたどり着いても
    必要な情報を得られるように

    View full-size slide

  41. 解決策2:参照 (リンク) を使う
    必要な情報が
    どこか1か所にだけ書いてある
    必要な情報が書いてあるところを参
    照できるようになっている
    どこにたどり着いても
    必要な情報を得られるように
    そこに無いから無いですね
    は避けられるが…
    実際はあまり読まれない

    View full-size slide

  42. 解決策2:すべての場所に漏れなく書く

    View full-size slide

  43. 解決策2:すべての場所に漏れなく書く
    同じ情報が数か所に書いてあるのに、
    ある情報は1か所にだけ書いてある
    必要な情報が書いてあるところを参
    照できるようになっている
    すべての場所に漏れなく書いてある
    どこにたどり着いても
    必要な情報を得られるように

    View full-size slide

  44. 解決策2:すべての場所に漏れなく書く
    必要な情報が
    どこか1か所にだけ書いてある
    必要な情報が書いてあるところを参
    照できるようになっている
    すべての場所に漏れなく書いてある
    どこにたどり着いても
    必要な情報を得られるように
    そこに無いから無いですね
    は避けられるが…
    漏れなく書く、を維持するのは大変

    View full-size slide

  45. 解決策3:根本治療を検討する
    • 同じような記事がいろいろなところに書いてあることに伸びし
    ろがありそう。
    • どこに書けばいいか、いつも悩む
    • 書いたつもりなんだけど、書いた⽂章が⾒つか
    らない
    • 書いてないと思って追加したら、同じような記
    事が⾒つかった。
    こういう経験があったら要注意

    View full-size slide

  46. 解決策3:根本治療を検討する
    どこに何を書くか (ルール) を決めましょう
    (執筆者として) 書く場所が明確 = (読者として) 読む場所が明確
    どこに何を書くか明確だと
    どこを読めばいいか明確になって
    「わかりやすい!」となりがち

    View full-size slide

  47. 解決策3:根本治療を検討する
    どこに何を書くか (ルール) を決めましょう
    (執筆者として) 書く場所が明確 = (読者として) 読む場所が明確
    どこに何を書くか明確だと
    どこを読めばいいか明確になって
    「わかりやすい!」となりがち
    よく使うルールを2つ紹介しましょう

    View full-size slide

  48. たとえば…
    • 管理者
    • 一般ユーザー
    たとえば…
    • クレジットカード払いを
    使っている人
    • 請求書払いを使っている人
    ルール1:対象読者ごとに書く場所を分ける
    読者が両方に所属することがない
    場合に使います
    両⽅に所属することがあっても、読者が今どの⽴場にいるか、
    強く意識できる場合にも使えます

    View full-size slide

  49. たとえば…
    • クレジットカード払いを
    使っている人
    • 請求書払いを使っている人
    ルール1:対象読者ごとに書く場所を分ける
    WIP

    View full-size slide

  50. たとえば…
    • 管理者
    • 一般ユーザー
    ルール1:対象読者ごとに書く場所を分ける
    管理者編
    ○×
    マニュアル
    ○×
    マニュアル
    ユーザー編
    たとえば…
    • 管理者
    • 経理・購買部門担当者 管理者編
    ○×
    マニュアル
    ○×
    マニュアル
    経理・購買部⾨
    担当者編

    View full-size slide

  51. たとえば…
    • 管理者
    • 一般ユーザー
    ルール1:対象読者ごとに書く場所を分ける
    管理者編
    ○×
    マニュアル
    ○×
    マニュアル
    ユーザー編
    アクセス管理 (SORACOM Access Management: SAM) の説明を分けるなら…
    SAM ユーザーを作る操作は「管理者編」に書いて、ユーザーに読ませないよう
    にします。
    SAM ユーザーを使う⼈に読んでほしい内容は「ユーザー編」に書きます。

    View full-size slide

  52. ルール1:対象読者ごとに書く場所を分ける
    たとえば…
    • 管理者
    • 経理・購買部門担当者 管理者編
    ○×
    マニュアル
    ○×
    マニュアル
    経理・購買部⾨
    担当者編
    ⽀払・購⼊に関する説明を
    「経理・購買部⾨担当者編」の
    外に漏らさない。絶対に

    View full-size slide

  53. ルール1:対象読者ごとに書く場所を分ける
    たとえば…
    • 管理者
    • 経理・購買部門担当者 管理者編
    ○×
    マニュアル
    ○×
    マニュアル
    経理・購買部⾨
    担当者編
    支払・購入に関する説明を
    「経理・購買部門担当者編」の
    外に漏らさない。絶対に
    対象読者ごとに書く場所を分けておくと、
    「この情報は、この読者にとって必要かどうか」
    という観点で記載場所を決定できる。
    書く場所に悩むことが激減します

    View full-size slide

  54. ルール2:機能/サービスごとに書く場所を分
    ける
    たとえば…
    • SORACOM Air for セルラー
    • SORACOM Air for LoRaWAN
    • SORACOM Air for Sigfox
    • SORACOM Arc
    :
    • SORACOM Mosaic
    • SORACOM Orbit
    「SORACOMユーザーコンソール」と
    か「認証情報ストア」のように多く
    のサービスで使われている機能は、
    どこに何を書くか悩みがち。

    View full-size slide

  55. ルール2:機能/サービスごとに書く場所を分
    ける
    「SORACOM ユーザーコンソール」を
    使って、「IoT SIM の名前を変更す
    る」操作の場合は、どこに書く?
    • SORACOM ユーザーコンソール?
    • SORACOM Air for セルラー?

    View full-size slide

  56. ルール2:機能/サービスごとに書く場所を分
    ける
    「SORACOM ユーザーコンソール」を
    使って、「IoT SIM の名前を変更す
    る」操作の場合は、どこに書く?
    • SORACOM ユーザーコンソール?
    • SORACOM Air for セルラー?
    悩んだらルール1に戻って対象読者を考える。
    (対象読者が少ないほうを選ぶといいかも)
    • SORACOM ユーザーコンソールを使う⼈
    • SORACOM Air for セルラーを使う人

    View full-size slide

  57. ルール2:機能/サービスごとに書く場所を分
    ける
    「Krypton」を使うときに「認証情報
    ストア」に X.509 証明書を登録する
    操作の場合は、どこに書く?
    • SORACOM ユーザーコンソール?
    • 認証情報ストア?
    • SORACOM Krypton?

    View full-size slide

  58. ルール2:機能/サービスごとに書く場所を分
    ける
    「Krypton」を使うときに「認証情報
    ストア」に X.509 証明書を登録する
    操作の場合は、どこに書く?
    • SORACOM ユーザーコンソール?
    • 認証情報ストア?
    • SORACOM Krypton?
    悩んだらルール1に戻って対象読者を考える。
    (対象読者が少ないほうを選ぶといいかも)
    • SORACOM ユーザーコンソールを使う⼈
    • 認証情報ストアを使う⼈
    • SORACOM Krypton を使う人

    View full-size slide

  59. ルール2:機能/サービスごとに書く場所を分
    ける
    ⼀⽅、認証情報ストアの画⾯を表⽰する操
    作 (右画⾯) は、認証情報ストアを使う⼈
    が対象読者になるので、「認証情報スト
    ア」として独⽴させても良さそう。

    View full-size slide

  60. たとえば…
    • 一回使ったらしばらく使わ
    ない
    • 例: 初期設定、⾔語設定
    • 主な機能として頻繁に使う
    • 例: データ通信量を確認する
    たとえばユーザーの中でも…
    • ほとんどの人が使う
    • 条件を満たす一部の人だけ
    が使う
    • 例: プログラムを書ける⼈だ
    けが使う
    ルール3:使用頻度によって書く場所を分ける
    そうは言っても、
    同じような記事が量産され
    ることはある

    View full-size slide

  61. たとえば…
    • 一回使ったらしばらく使わ
    ない
    • 例: 初期設定、⾔語設定
    • 主な機能として頻繁に使う
    • 例: データ通信量を確認する
    たとえばユーザーの中でも…
    • ほとんどの人が使う
    • 条件を満たす一部の人だけ
    が使う
    • 例: プログラムを書ける⼈だ
    けが使う
    ルール3:使用頻度によって書く場所を分ける
    うまく分けられずに、同じ
    ような記事が量産されるこ
    とはある
    同じ情報が数か所に書いてあるのに、
    ある情報は1か所にだけ書いてある
    必要な情報が書いてあるところを参
    照できるようになっている
    すべての場所に漏れなく書いてある
    どこにたどり着いても
    必要な情報を得られるように

    View full-size slide

  62. どこに何を書くか (ルー
    ル) を決めましょう。
    • 対象読者で書く場所を決
    める
    • 機能で書く場所を決める
    まとめ
    そこに無いから無いですねと判断されないように、どこにたどり
    着いても必要な情報を得られるように気を配りましょう。
    • 必要な情報に誘導するた
    めに参照 (リンク) を使う
    • その情報が必要になるす
    べての場所に同じ内容を
    コピーする

    View full-size slide

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

    View full-size slide