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

LINE Technical Writing Meetup vol.14

LINE Technical Writing Meetup vol.14

2022年7月14日開催

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

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

SORACOM
PRO

July 26, 2022
Tweet

More Decks by SORACOM

Other Decks in Business

Transcript

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

  2. 自己紹介 • 矢崎 誠 (makoto) • 株式会社ソラコム Technical Writer •

    テクニカルライター歴: 約25年。前職はLINE 株式会社。 • Twitter: @yazakimakoto https://www.amazon.co.jp/dp/4902820102 おすすめの本→
  3. 株式会社ソラコム 概要 商号 株式会社ソラコム / SORACOM, INC. 代表取締役社長 玉川 憲

    事業概要 IoT プラットフォームの提供 拠点 日本、英国、米国(シアトル) 2017年8月に KDDI グループ入り
  4. IoT とは? メーター (ガス・電気) 温度計 デジタル化 { "gas_volume": 426.807, "temperature":

    30 } { "air_conditioner": true, "target_temperature": 28 } 遠隔操作 エアコン クラウド 自宅
  5. IoT とは? モノやコトをデジタル化 現場を知る、現場を動かす クラウド センサー/デバイス ネットワーク 現場のモノやコトを デジタル化 現場とクラウドを

    つなげる 現場のデジタル データを活用
  6. SORACOM は IoT の「つなぐ」を簡単に センサー/デバイス クラウド ü 遠隔操作 ü メンテナンス

    ü 蓄積・見える化 ü アラート通知 通信 デバイス センサー キット ネットワーク IoT SIM LPWA パートナー デバイス パートナークラウド (AWS / Microsoft / Google / IBM) Wi-Fi / 有線 3G / LTE / 5G LTE-M
  7. 書きやすい文書 / 探しやすい文書を 書くコツ

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

  9. わかりやすい文章を書くコツは ⾃分が書いた⽂章にうまくたどり着けた⼈に、正しく意図を伝 えるためのコツ ところで… 読者は、あなたが書いた⽂章に たどり着けますか…?

  10. わかりやすい文章を書くコツは ⾃分が書いた⽂章にうまくたどり着けた⼈に、正しく意図を伝 えるためのコツ ところで… 読者は、あなたが書いた⽂章に たどり着けますか…? 読者は、あなたが書いた多くの⽂ 章から、読者 (⾃分) が必要と

    考えている情報を探せますか…?
  11. そもそも その⽂章、どこに書いてあるの? (読者の視点)

  12. そもそも その⽂章、どこに書いてあるの? (読者の視点) その⽂章、どこに書くの? (執筆者の視点)

  13. (コツ 1) ユーザーが知っている ことを目次に出す

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

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

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

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

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

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

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

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

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

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

    を管理する • イベントを確認する • アカウントを管理する 良くない例: 画面に表示されている内容をそ のまま目次に出す 開発者ができると思っていることを⽬ 次に出すと 「わかりにくい!」となりがち
  24. ユーザーが知っていることを目次に出す ソラカメが「動画をクラウ ドに保存するサービス」と 分かって買っている。 「動画をクラウドに保存す る」ことが書いてありそう なタイトルを⽤意する。

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

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

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

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

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

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

    ユーザーができると思っていることを目次に 出す ユーザーが知っていることを⽬次に出 すと「わかりやすい!」となりがち これがよく⾔われる「ユーザーの立場 になって考える」だと思います
  31. • ATOM アプリの初期設定 をする • 通知を確認する • ATOM Cam 2

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

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

    ユーザーができると思っていることを目次に 出す ユーザーができると思っていることを ⽬次に出すと 「わかりやすい!」となりがち これがよく⾔われる「ユーザーの立場 になって考える」だと思います 相手が知っていることをベースに説明す ると「わかりやすい!」となりがち あなたが知っていることをベースに説明 すると「わかりにくい!」となりがち どんなときも一緒です(たぶん) ドキュメント以外の場⾯では私も苦⼿です。すみません。。。
  34. (コツ 2) そこに無いから無いですね という原則を忘れない

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

    判断しがちです。
  36. 良くない例: 同じ内容がいろいろなところに 書いてある たとえば…

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

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

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

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

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

    は避けられるが… 実際はあまり読まれない
  42. 解決策2:すべての場所に漏れなく書く

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

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

    漏れなく書く、を維持するのは大変
  45. 解決策3:根本治療を検討する • 同じような記事がいろいろなところに書いてあることに伸びし ろがありそう。 • どこに書けばいいか、いつも悩む • 書いたつもりなんだけど、書いた⽂章が⾒つか らない •

    書いてないと思って追加したら、同じような記 事が⾒つかった。 こういう経験があったら要注意
  46. 解決策3:根本治療を検討する どこに何を書くか (ルール) を決めましょう (執筆者として) 書く場所が明確 = (読者として) 読む場所が明確 どこに何を書くか明確だと

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

    どこを読めばいいか明確になって 「わかりやすい!」となりがち よく使うルールを2つ紹介しましょう
  48. たとえば… • 管理者 • 一般ユーザー たとえば… • クレジットカード払いを 使っている人 •

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

  50. たとえば… • 管理者 • 一般ユーザー ルール1:対象読者ごとに書く場所を分ける 管理者編 ◦× マニュアル ◦×

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

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

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

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

    Air for LoRaWAN • SORACOM Air for Sigfox • SORACOM Arc : • SORACOM Mosaic • SORACOM Orbit 「SORACOMユーザーコンソール」と か「認証情報ストア」のように多く のサービスで使われている機能は、 どこに何を書くか悩みがち。
  55. ルール2:機能/サービスごとに書く場所を分 ける 「SORACOM ユーザーコンソール」を 使って、「IoT SIM の名前を変更す る」操作の場合は、どこに書く? • SORACOM

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

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

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

    • 認証情報ストア? • SORACOM Krypton? 悩んだらルール1に戻って対象読者を考える。 (対象読者が少ないほうを選ぶといいかも) • SORACOM ユーザーコンソールを使う⼈ • 認証情報ストアを使う⼈ • SORACOM Krypton を使う人
  59. ルール2:機能/サービスごとに書く場所を分 ける ⼀⽅、認証情報ストアの画⾯を表⽰する操 作 (右画⾯) は、認証情報ストアを使う⼈ が対象読者になるので、「認証情報スト ア」として独⽴させても良さそう。

  60. たとえば… • 一回使ったらしばらく使わ ない • 例: 初期設定、⾔語設定 • 主な機能として頻繁に使う •

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

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

    そこに無いから無いですねと判断されないように、どこにたどり 着いても必要な情報を得られるように気を配りましょう。 • 必要な情報に誘導するた めに参照 (リンク) を使う • その情報が必要になるす べての場所に同じ内容を コピーする
  63. ご清聴ありがとうございました! Twitter: @yazakimakoto