LINE Technical Writing Meetup vol.14

by SORACOM（ソラコム）

Embed

Start on current slide

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

Slide 22

Slide 22 text

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