LINE Technical Writing Meetup vol.14
by
SORACOM
Link
Embed
Share
Beginning
This slide
Copy link URL
Copy link URL
Copy iframe embed code
Copy iframe embed code
Copy javascript embed code
Copy javascript embed code
Share
Tweet
Share
Tweet
Slide 1
Slide 1 text
書きやすい文書 / 探しやすい文書を 書くコツ
Slide 2
Slide 2 text
自己紹介 • 矢崎 誠 (makoto) • 株式会社ソラコム Technical Writer • テクニカルライター歴: 約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 とは? メーター (ガス・電気) 温度計 デジタル化 { "gas_volume": 426.807, "temperature": 30 } { "air_conditioner": true, "target_temperature": 28 } 遠隔操作 エアコン クラウド 自宅
Slide 5
Slide 5 text
IoT とは? モノやコトをデジタル化 現場を知る、現場を動かす クラウド センサー/デバイス ネットワーク 現場のモノやコトを デジタル化 現場とクラウドを つなげる 現場のデジタル データを活用
Slide 6
Slide 6 text
SORACOM は IoT の「つなぐ」を簡単に センサー/デバイス クラウド ü 遠隔操作 ü メンテナンス ü 蓄積・見える化 ü アラート通知 通信 デバイス センサー キット ネットワーク IoT SIM LPWA パートナー デバイス パートナークラウド (AWS / Microsoft / Google / IBM) Wi-Fi / 有線 3G / LTE / 5G LTE-M
Slide 7
Slide 7 text
書きやすい文書 / 探しやすい文書を 書くコツ
Slide 8
Slide 8 text
わかりやすい文章を書くコツは ⾃分が書いた⽂章にうまくたどり着けた⼈に、正しく意図を伝 えるためのコツ
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
(コツ 1) ユーザーが知っている ことを目次に出す
Slide 14
Slide 14 text
https://soracom.jp/store/20834/
Slide 15
Slide 15 text
https://soracom.jp/store/20834/
Slide 16
Slide 16 text
読者は必要な情報をどうやって見つけるの? ⼀般的には⽬次を眺めます。
Slide 17
Slide 17 text
読者は必要な情報をどうやって見つけるの? ⼀般的には⽬次を眺めます。 頑張っていい⽬次を作りま しょう。
Slide 18
Slide 18 text
読者は必要な情報をどうやって見つけるの? ⼀般的には⽬次を眺めます。 頑張っていい⽬次を作りま しょう。 いい目次とは?
Slide 19
Slide 19 text
読者は必要な情報をどうやって見つけるの? ⼀般的には⽬次を眺めます。 頑張っていい⽬次を作りま しょう。 いい目次とは? どんな⽬次にすると、 必要な情報を⾒つけられる いい⽬次になる?
Slide 20
Slide 20 text
• ATOM アプリの初期設定を する • 通知を確認する • ATOM Cam 2 を管理する • イベントを確認する • アカウントを管理する 良くない例: 画面に表示されている内容をそ のまま目次に出す
Slide 21
Slide 21 text
• ATOM アプリの初期設定を する • 通知を確認する • ATOM Cam 2 を管理する • イベントを確認する • アカウントを管理する 良くない例: 画面に表示されている内容をそ のまま目次に出す
Slide 22
Slide 22 text
• ATOM アプリの初期設定を する • 通知を確認する • ATOM Cam 2 を管理する • イベントを確認する • アカウントを管理する 良くない例: 画面に表示されている内容をそ のまま目次に出す
Slide 23
Slide 23 text
• ATOM アプリの初期設定を する • 通知を確認する • ATOM Cam 2 を管理する • イベントを確認する • アカウントを管理する 良くない例: 画面に表示されている内容をそ のまま目次に出す 開発者ができると思っていることを⽬ 次に出すと 「わかりにくい!」となりがち
Slide 24
Slide 24 text
ユーザーが知っていることを目次に出す ソラカメが「動画をクラウ ドに保存するサービス」と 分かって買っている。 「動画をクラウドに保存す る」ことが書いてありそう なタイトルを⽤意する。
Slide 25
Slide 25 text
• カメラを設置する必要がある • スマホアプリが必要そう • リアルタイム監視に使えそう • 録画された映像を⾒られそう • モーション検知できそう ユーザーが知っていることを目次に出す https://soracom.jp/store/20834/
Slide 26
Slide 26 text
• カメラを設置する必要がある • スマホアプリが必要そう • リアルタイム監視に使えそう • 録画された映像を⾒られそう • モーション検知できそう ユーザーが知っていることを目次に出す
Slide 27
Slide 27 text
• カメラを設置する必要がある • スマホアプリが必要そう • リアルタイム監視に使えそう • 録画された映像を⾒られそう • モーション検知できそう ユーザーが知っていることを目次に出す
Slide 28
Slide 28 text
• カメラを設置する必要がある • スマホアプリが必要そう • リアルタイム監視に使えそう • 録画された映像を⾒られそう • モーション検知できそう ユーザーが知っていることを目次に出す
Slide 29
Slide 29 text
• カメラを設置する必要がある • スマホアプリが必要そう • リアルタイム監視に使えそう • 録画された映像を⾒られそう • モーション検知できそう ユーザーができると思っていることを目次に 出す ユーザーが知っていることを⽬次に出 すと「わかりやすい!」となりがち
Slide 30
Slide 30 text
• カメラを設置する必要がある • スマホアプリが必要そう • リアルタイム監視に使えそう • 録画された映像を⾒られそう • モーション検知できそう ユーザーができると思っていることを目次に 出す ユーザーが知っていることを⽬次に出 すと「わかりやすい!」となりがち これがよく⾔われる「ユーザーの立場 になって考える」だと思います
Slide 31
Slide 31 text
• ATOM アプリの初期設定 をする • 通知を確認する • ATOM Cam 2 を管理す る • イベントを確認する • アカウントを管理する ユーザーが知っていることを目次に出す
Slide 32
Slide 32 text
• カメラを設置する必要がある • スマホアプリが必要そう • リアルタイム監視に使えそう • 録画された映像を⾒られそう • モーション検知できそう ユーザーができると思っていることを目次に 出す ユーザーができると思っていることを ⽬次に出すと 「わかりやすい!」となりがち これがよく⾔われる「ユーザーの立場 になって考える」だと思います ユーザーが知っていることを⽬次に出 すと「わかりやすい!」となりがち 開発者が知っていることを⽬次に出す と「わかりにくい!」となりがち まとめ
Slide 33
Slide 33 text
• カメラを設置する必要がある • スマホアプリが必要そう • リアルタイム監視に使えそう • 録画された映像を⾒られそう • モーション検知できそう ユーザーができると思っていることを目次に 出す ユーザーができると思っていることを ⽬次に出すと 「わかりやすい!」となりがち これがよく⾔われる「ユーザーの立場 になって考える」だと思います 相手が知っていることをベースに説明す ると「わかりやすい!」となりがち あなたが知っていることをベースに説明 すると「わかりにくい!」となりがち どんなときも一緒です(たぶん) ドキュメント以外の場⾯では私も苦⼿です。すみません。。。
Slide 34
Slide 34 text
(コツ 2) そこに無いから無いですね という原則を忘れない
Slide 35
Slide 35 text
良くない例: 同じ内容がいろいろなところに 書いてある 「⽀払⽅法を設定する操作」が 数か所に書かれているとします。 どこか1か所にたどり着いた⼈は、 ほかのところに似たようなこと が書いてないと考えがちです。 ⾒つけたページに書いていない なら「どこにも説明がない」と 判断しがちです。
Slide 36
Slide 36 text
良くない例: 同じ内容がいろいろなところに 書いてある たとえば…
Slide 37
Slide 37 text
良くない例: 同じ内容がいろいろなところに 書いてある たとえば… そこに無いから無いですね
Slide 38
Slide 38 text
良くない例: 同じ内容がいろいろなところに 書いてある たとえば… そこに無いから無いですね 同じ情報が数か所に書いてあるのに、 ある情報は1か所にだけ書いてある どこにたどり着いても 必要な情報を得られるように
Slide 39
Slide 39 text
解決策1:参照 (リンク) を使う
Slide 40
Slide 40 text
解決策2:参照 (リンク) を使う 同じ情報が数か所に書いてあるのに、 ある情報は1か所にだけ書いてある 必要な情報が書いてあるところを参 照できるようになっている どこにたどり着いても 必要な情報を得られるように
Slide 41
Slide 41 text
解決策2:参照 (リンク) を使う 必要な情報が どこか1か所にだけ書いてある 必要な情報が書いてあるところを参 照できるようになっている どこにたどり着いても 必要な情報を得られるように そこに無いから無いですね は避けられるが… 実際はあまり読まれない
Slide 42
Slide 42 text
解決策2:すべての場所に漏れなく書く
Slide 43
Slide 43 text
解決策2:すべての場所に漏れなく書く 同じ情報が数か所に書いてあるのに、 ある情報は1か所にだけ書いてある 必要な情報が書いてあるところを参 照できるようになっている すべての場所に漏れなく書いてある どこにたどり着いても 必要な情報を得られるように
Slide 44
Slide 44 text
解決策2:すべての場所に漏れなく書く 必要な情報が どこか1か所にだけ書いてある 必要な情報が書いてあるところを参 照できるようになっている すべての場所に漏れなく書いてある どこにたどり着いても 必要な情報を得られるように そこに無いから無いですね は避けられるが… 漏れなく書く、を維持するのは大変
Slide 45
Slide 45 text
解決策3:根本治療を検討する • 同じような記事がいろいろなところに書いてあることに伸びし ろがありそう。 • どこに書けばいいか、いつも悩む • 書いたつもりなんだけど、書いた⽂章が⾒つか らない • 書いてないと思って追加したら、同じような記 事が⾒つかった。 こういう経験があったら要注意
Slide 46
Slide 46 text
解決策3:根本治療を検討する どこに何を書くか (ルール) を決めましょう (執筆者として) 書く場所が明確 = (読者として) 読む場所が明確 どこに何を書くか明確だと どこを読めばいいか明確になって 「わかりやすい!」となりがち
Slide 47
Slide 47 text
解決策3:根本治療を検討する どこに何を書くか (ルール) を決めましょう (執筆者として) 書く場所が明確 = (読者として) 読む場所が明確 どこに何を書くか明確だと どこを読めばいいか明確になって 「わかりやすい!」となりがち よく使うルールを2つ紹介しましょう
Slide 48
Slide 48 text
たとえば… • 管理者 • 一般ユーザー たとえば… • クレジットカード払いを 使っている人 • 請求書払いを使っている人 ルール1:対象読者ごとに書く場所を分ける 読者が両方に所属することがない 場合に使います 両⽅に所属することがあっても、読者が今どの⽴場にいるか、 強く意識できる場合にも使えます
Slide 49
Slide 49 text
たとえば… • クレジットカード払いを 使っている人 • 請求書払いを使っている人 ルール1:対象読者ごとに書く場所を分ける WIP
Slide 50
Slide 50 text
たとえば… • 管理者 • 一般ユーザー ルール1:対象読者ごとに書く場所を分ける 管理者編 ○× マニュアル ○× マニュアル ユーザー編 たとえば… • 管理者 • 経理・購買部門担当者 管理者編 ○× マニュアル ○× マニュアル 経理・購買部⾨ 担当者編
Slide 51
Slide 51 text
たとえば… • 管理者 • 一般ユーザー ルール1:対象読者ごとに書く場所を分ける 管理者編 ○× マニュアル ○× マニュアル ユーザー編 アクセス管理 (SORACOM Access Management: SAM) の説明を分けるなら… SAM ユーザーを作る操作は「管理者編」に書いて、ユーザーに読ませないよう にします。 SAM ユーザーを使う⼈に読んでほしい内容は「ユーザー編」に書きます。
Slide 52
Slide 52 text
ルール1:対象読者ごとに書く場所を分ける たとえば… • 管理者 • 経理・購買部門担当者 管理者編 ○× マニュアル ○× マニュアル 経理・購買部⾨ 担当者編 ⽀払・購⼊に関する説明を 「経理・購買部⾨担当者編」の 外に漏らさない。絶対に
Slide 53
Slide 53 text
ルール1:対象読者ごとに書く場所を分ける たとえば… • 管理者 • 経理・購買部門担当者 管理者編 ○× マニュアル ○× マニュアル 経理・購買部⾨ 担当者編 支払・購入に関する説明を 「経理・購買部門担当者編」の 外に漏らさない。絶対に 対象読者ごとに書く場所を分けておくと、 「この情報は、この読者にとって必要かどうか」 という観点で記載場所を決定できる。 書く場所に悩むことが激減します
Slide 54
Slide 54 text
ルール2:機能/サービスごとに書く場所を分 ける たとえば… • SORACOM Air for セルラー • SORACOM Air for LoRaWAN • SORACOM Air for Sigfox • SORACOM Arc : • SORACOM Mosaic • SORACOM Orbit 「SORACOMユーザーコンソール」と か「認証情報ストア」のように多く のサービスで使われている機能は、 どこに何を書くか悩みがち。
Slide 55
Slide 55 text
ルール2:機能/サービスごとに書く場所を分 ける 「SORACOM ユーザーコンソール」を 使って、「IoT SIM の名前を変更す る」操作の場合は、どこに書く? • SORACOM ユーザーコンソール? • SORACOM Air for セルラー?
Slide 56
Slide 56 text
ルール2:機能/サービスごとに書く場所を分 ける 「SORACOM ユーザーコンソール」を 使って、「IoT SIM の名前を変更す る」操作の場合は、どこに書く? • SORACOM ユーザーコンソール? • SORACOM Air for セルラー? 悩んだらルール1に戻って対象読者を考える。 (対象読者が少ないほうを選ぶといいかも) • SORACOM ユーザーコンソールを使う⼈ • SORACOM Air for セルラーを使う人
Slide 57
Slide 57 text
ルール2:機能/サービスごとに書く場所を分 ける 「Krypton」を使うときに「認証情報 ストア」に X.509 証明書を登録する 操作の場合は、どこに書く? • SORACOM ユーザーコンソール? • 認証情報ストア? • SORACOM Krypton?
Slide 58
Slide 58 text
ルール2:機能/サービスごとに書く場所を分 ける 「Krypton」を使うときに「認証情報 ストア」に X.509 証明書を登録する 操作の場合は、どこに書く? • SORACOM ユーザーコンソール? • 認証情報ストア? • SORACOM Krypton? 悩んだらルール1に戻って対象読者を考える。 (対象読者が少ないほうを選ぶといいかも) • SORACOM ユーザーコンソールを使う⼈ • 認証情報ストアを使う⼈ • SORACOM Krypton を使う人
Slide 59
Slide 59 text
ルール2:機能/サービスごとに書く場所を分 ける ⼀⽅、認証情報ストアの画⾯を表⽰する操 作 (右画⾯) は、認証情報ストアを使う⼈ が対象読者になるので、「認証情報スト ア」として独⽴させても良さそう。
Slide 60
Slide 60 text
たとえば… • 一回使ったらしばらく使わ ない • 例: 初期設定、⾔語設定 • 主な機能として頻繁に使う • 例: データ通信量を確認する たとえばユーザーの中でも… • ほとんどの人が使う • 条件を満たす一部の人だけ が使う • 例: プログラムを書ける⼈だ けが使う ルール3:使用頻度によって書く場所を分ける そうは言っても、 同じような記事が量産され ることはある
Slide 61
Slide 61 text
たとえば… • 一回使ったらしばらく使わ ない • 例: 初期設定、⾔語設定 • 主な機能として頻繁に使う • 例: データ通信量を確認する たとえばユーザーの中でも… • ほとんどの人が使う • 条件を満たす一部の人だけ が使う • 例: プログラムを書ける⼈だ けが使う ルール3:使用頻度によって書く場所を分ける うまく分けられずに、同じ ような記事が量産されるこ とはある 同じ情報が数か所に書いてあるのに、 ある情報は1か所にだけ書いてある 必要な情報が書いてあるところを参 照できるようになっている すべての場所に漏れなく書いてある どこにたどり着いても 必要な情報を得られるように
Slide 62
Slide 62 text
どこに何を書くか (ルー ル) を決めましょう。 • 対象読者で書く場所を決 める • 機能で書く場所を決める まとめ そこに無いから無いですねと判断されないように、どこにたどり 着いても必要な情報を得られるように気を配りましょう。 • 必要な情報に誘導するた めに参照 (リンク) を使う • その情報が必要になるす べての場所に同じ内容を コピーする
Slide 63
Slide 63 text
ご清聴ありがとうございました! Twitter: @yazakimakoto