2022年7月14日開催
テクニカルライティングをテーマにした技術者向けのミートアップ LINE Technical Writing Meetup vol. 14
書きやすい文書 / 探しやすい文書を書くコツ 株式会社ソラコム テクニカルライター 矢崎 誠
書きやすい文書 / 探しやすい文書を書くコツ
View Slide
自己紹介• 矢崎 誠 (makoto)• 株式会社ソラコム Technical Writer• テクニカルライター歴: 約25年。前職はLINE株式会社。• Twitter: @yazakimakotohttps://www.amazon.co.jp/dp/4902820102おすすめの本→
株式会社ソラコム 概要商号 株式会社ソラコム / SORACOM, INC.代表取締役社長 玉川 憲事業概要 IoT プラットフォームの提供拠点 日本、英国、米国(シアトル)2017年8月に KDDI グループ入り
IoT とは？メーター(ガス・電気)温度計デジタル化{"gas_volume": 426.807,"temperature": 30}{"air_conditioner": true,"target_temperature": 28}遠隔操作エアコンクラウド自宅
IoT とは？モノやコトをデジタル化現場を知る、現場を動かすクラウドセンサー/デバイス ネットワーク現場のモノやコトをデジタル化現場とクラウドをつなげる現場のデジタルデータを活用
SORACOM は IoT の「つなぐ」を簡単にセンサー/デバイス クラウドü 遠隔操作ü メンテナンスü 蓄積・見える化ü アラート通知通信デバイスセンサーキットネットワークIoT SIMLPWAパートナーデバイスパートナークラウド(AWS / Microsoft / Google / IBM)Wi-Fi / 有線3G / LTE / 5GLTE-M
わかりやすい文章を書くコツは⾃分が書いた⽂章にうまくたどり着けた⼈に、正しく意図を伝えるためのコツ
わかりやすい文章を書くコツは⾃分が書いた⽂章にうまくたどり着けた⼈に、正しく意図を伝えるためのコツところで…読者は、あなたが書いた⽂章にたどり着けますか…？
わかりやすい文章を書くコツは⾃分が書いた⽂章にうまくたどり着けた⼈に、正しく意図を伝えるためのコツところで…読者は、あなたが書いた⽂章にたどり着けますか…？読者は、あなたが書いた多くの⽂章から、読者 (⾃分) が必要と考えている情報を探せますか…？
そもそもその⽂章、どこに書いてあるの？ (読者の視点)
そもそもその⽂章、どこに書いてあるの？ (読者の視点)その⽂章、どこに書くの？ (執筆者の視点)
(コツ 1) ユーザーが知っていることを目次に出す
https://soracom.jp/store/20834/
読者は必要な情報をどうやって見つけるの？⼀般的には⽬次を眺めます。
読者は必要な情報をどうやって見つけるの？⼀般的には⽬次を眺めます。頑張っていい⽬次を作りましょう。
読者は必要な情報をどうやって見つけるの？⼀般的には⽬次を眺めます。頑張っていい⽬次を作りましょう。いい目次とは？
読者は必要な情報をどうやって見つけるの？⼀般的には⽬次を眺めます。頑張っていい⽬次を作りましょう。いい目次とは？どんな⽬次にすると、必要な情報を⾒つけられるいい⽬次になる？
• ATOM アプリの初期設定をする• 通知を確認する• ATOM Cam 2 を管理する• イベントを確認する• アカウントを管理する良くない例: 画面に表示されている内容をそのまま目次に出す
• ATOM アプリの初期設定をする• 通知を確認する• ATOM Cam 2 を管理する• イベントを確認する• アカウントを管理する良くない例: 画面に表示されている内容をそのまま目次に出す開発者ができると思っていることを⽬次に出すと「わかりにくい！」となりがち
ユーザーが知っていることを目次に出すソラカメが「動画をクラウドに保存するサービス」と分かって買っている。「動画をクラウドに保存する」ことが書いてありそうなタイトルを⽤意する。
• カメラを設置する必要がある• スマホアプリが必要そう• リアルタイム監視に使えそう• 録画された映像を⾒られそう• モーション検知できそうユーザーが知っていることを目次に出すhttps://soracom.jp/store/20834/
• カメラを設置する必要がある• スマホアプリが必要そう• リアルタイム監視に使えそう• 録画された映像を⾒られそう• モーション検知できそうユーザーが知っていることを目次に出す
• カメラを設置する必要がある• スマホアプリが必要そう• リアルタイム監視に使えそう• 録画された映像を⾒られそう• モーション検知できそうユーザーができると思っていることを目次に出すユーザーが知っていることを⽬次に出すと「わかりやすい！」となりがち
• カメラを設置する必要がある• スマホアプリが必要そう• リアルタイム監視に使えそう• 録画された映像を⾒られそう• モーション検知できそうユーザーができると思っていることを目次に出すユーザーが知っていることを⽬次に出すと「わかりやすい！」となりがちこれがよく⾔われる「ユーザーの立場になって考える」だと思います
• ATOM アプリの初期設定をする• 通知を確認する• ATOM Cam 2 を管理する• イベントを確認する• アカウントを管理するユーザーが知っていることを目次に出す
• カメラを設置する必要がある• スマホアプリが必要そう• リアルタイム監視に使えそう• 録画された映像を⾒られそう• モーション検知できそうユーザーができると思っていることを目次に出すユーザーができると思っていることを⽬次に出すと「わかりやすい！」となりがちこれがよく⾔われる「ユーザーの立場になって考える」だと思いますユーザーが知っていることを⽬次に出すと「わかりやすい！」となりがち開発者が知っていることを⽬次に出すと「わかりにくい！」となりがちまとめ
• カメラを設置する必要がある• スマホアプリが必要そう• リアルタイム監視に使えそう• 録画された映像を⾒られそう• モーション検知できそうユーザーができると思っていることを目次に出すユーザーができると思っていることを⽬次に出すと「わかりやすい！」となりがちこれがよく⾔われる「ユーザーの立場になって考える」だと思います相手が知っていることをベースに説明すると「わかりやすい！」となりがちあなたが知っていることをベースに説明すると「わかりにくい！」となりがちどんなときも一緒です(たぶん)ドキュメント以外の場⾯では私も苦⼿です。すみません。。。
(コツ 2) そこに無いから無いですねという原則を忘れない
良くない例: 同じ内容がいろいろなところに書いてある「⽀払⽅法を設定する操作」が数か所に書かれているとします。どこか1か所にたどり着いた⼈は、ほかのところに似たようなことが書いてないと考えがちです。⾒つけたページに書いていないなら「どこにも説明がない」と判断しがちです。
良くない例: 同じ内容がいろいろなところに書いてあるたとえば…
良くない例: 同じ内容がいろいろなところに書いてあるたとえば…そこに無いから無いですね
良くない例: 同じ内容がいろいろなところに書いてあるたとえば…そこに無いから無いですね同じ情報が数か所に書いてあるのに、ある情報は1か所にだけ書いてあるどこにたどり着いても必要な情報を得られるように
解決策1:参照 (リンク) を使う
解決策2:参照 (リンク) を使う同じ情報が数か所に書いてあるのに、ある情報は1か所にだけ書いてある必要な情報が書いてあるところを参照できるようになっているどこにたどり着いても必要な情報を得られるように
解決策2:参照 (リンク) を使う必要な情報がどこか1か所にだけ書いてある必要な情報が書いてあるところを参照できるようになっているどこにたどり着いても必要な情報を得られるようにそこに無いから無いですねは避けられるが…実際はあまり読まれない
解決策2:すべての場所に漏れなく書く
解決策2:すべての場所に漏れなく書く同じ情報が数か所に書いてあるのに、ある情報は1か所にだけ書いてある必要な情報が書いてあるところを参照できるようになっているすべての場所に漏れなく書いてあるどこにたどり着いても必要な情報を得られるように
解決策2:すべての場所に漏れなく書く必要な情報がどこか1か所にだけ書いてある必要な情報が書いてあるところを参照できるようになっているすべての場所に漏れなく書いてあるどこにたどり着いても必要な情報を得られるようにそこに無いから無いですねは避けられるが…漏れなく書く、を維持するのは大変
解決策3:根本治療を検討する• 同じような記事がいろいろなところに書いてあることに伸びしろがありそう。• どこに書けばいいか、いつも悩む• 書いたつもりなんだけど、書いた⽂章が⾒つからない• 書いてないと思って追加したら、同じような記事が⾒つかった。こういう経験があったら要注意
解決策3:根本治療を検討するどこに何を書くか (ルール) を決めましょう(執筆者として) 書く場所が明確 ＝ (読者として) 読む場所が明確どこに何を書くか明確だとどこを読めばいいか明確になって「わかりやすい！」となりがち
解決策3:根本治療を検討するどこに何を書くか (ルール) を決めましょう(執筆者として) 書く場所が明確 ＝ (読者として) 読む場所が明確どこに何を書くか明確だとどこを読めばいいか明確になって「わかりやすい！」となりがちよく使うルールを2つ紹介しましょう
たとえば…• 管理者• 一般ユーザーたとえば…• クレジットカード払いを使っている人• 請求書払いを使っている人ルール1:対象読者ごとに書く場所を分ける読者が両方に所属することがない場合に使います両⽅に所属することがあっても、読者が今どの⽴場にいるか、強く意識できる場合にも使えます
たとえば…• クレジットカード払いを使っている人• 請求書払いを使っている人ルール1:対象読者ごとに書く場所を分けるWIP
たとえば…• 管理者• 一般ユーザールール1:対象読者ごとに書く場所を分ける管理者編○×マニュアル○×マニュアルユーザー編たとえば…• 管理者• 経理・購買部門担当者 管理者編○×マニュアル○×マニュアル経理・購買部⾨担当者編
たとえば…• 管理者• 一般ユーザールール1:対象読者ごとに書く場所を分ける管理者編○×マニュアル○×マニュアルユーザー編アクセス管理 (SORACOM Access Management: SAM) の説明を分けるなら…SAM ユーザーを作る操作は「管理者編」に書いて、ユーザーに読ませないようにします。SAM ユーザーを使う⼈に読んでほしい内容は「ユーザー編」に書きます。
ルール1:対象読者ごとに書く場所を分けるたとえば…• 管理者• 経理・購買部門担当者 管理者編○×マニュアル○×マニュアル経理・購買部⾨担当者編⽀払・購⼊に関する説明を「経理・購買部⾨担当者編」の外に漏らさない。絶対に
ルール1:対象読者ごとに書く場所を分けるたとえば…• 管理者• 経理・購買部門担当者 管理者編○×マニュアル○×マニュアル経理・購買部⾨担当者編支払・購入に関する説明を「経理・購買部門担当者編」の外に漏らさない。絶対に対象読者ごとに書く場所を分けておくと、「この情報は、この読者にとって必要かどうか」という観点で記載場所を決定できる。書く場所に悩むことが激減します
ルール2:機能/サービスごとに書く場所を分けるたとえば…• SORACOM Air for セルラー• SORACOM Air for LoRaWAN• SORACOM Air for Sigfox• SORACOM Arc:• SORACOM Mosaic• SORACOM Orbit「SORACOMユーザーコンソール」とか「認証情報ストア」のように多くのサービスで使われている機能は、どこに何を書くか悩みがち。
ルール2:機能/サービスごとに書く場所を分ける「SORACOM ユーザーコンソール」を使って、「IoT SIM の名前を変更する」操作の場合は、どこに書く？• SORACOM ユーザーコンソール？• SORACOM Air for セルラー？
ルール2:機能/サービスごとに書く場所を分ける「SORACOM ユーザーコンソール」を使って、「IoT SIM の名前を変更する」操作の場合は、どこに書く？• SORACOM ユーザーコンソール？• SORACOM Air for セルラー？悩んだらルール1に戻って対象読者を考える。(対象読者が少ないほうを選ぶといいかも)• SORACOM ユーザーコンソールを使う⼈• SORACOM Air for セルラーを使う人
ルール2:機能/サービスごとに書く場所を分ける「Krypton」を使うときに「認証情報ストア」に X.509 証明書を登録する操作の場合は、どこに書く？• SORACOM ユーザーコンソール？• 認証情報ストア？• SORACOM Krypton？
ルール2:機能/サービスごとに書く場所を分ける「Krypton」を使うときに「認証情報ストア」に X.509 証明書を登録する操作の場合は、どこに書く？• SORACOM ユーザーコンソール？• 認証情報ストア？• SORACOM Krypton？悩んだらルール1に戻って対象読者を考える。(対象読者が少ないほうを選ぶといいかも)• SORACOM ユーザーコンソールを使う⼈• 認証情報ストアを使う⼈• SORACOM Krypton を使う人
ルール2:機能/サービスごとに書く場所を分ける⼀⽅、認証情報ストアの画⾯を表⽰する操作 (右画⾯) は、認証情報ストアを使う⼈が対象読者になるので、「認証情報ストア」として独⽴させても良さそう。
たとえば…• 一回使ったらしばらく使わない• 例: 初期設定、⾔語設定• 主な機能として頻繁に使う• 例: データ通信量を確認するたとえばユーザーの中でも…• ほとんどの人が使う• 条件を満たす一部の人だけが使う• 例: プログラムを書ける⼈だけが使うルール3:使用頻度によって書く場所を分けるそうは言っても、同じような記事が量産されることはある
たとえば…• 一回使ったらしばらく使わない• 例: 初期設定、⾔語設定• 主な機能として頻繁に使う• 例: データ通信量を確認するたとえばユーザーの中でも…• ほとんどの人が使う• 条件を満たす一部の人だけが使う• 例: プログラムを書ける⼈だけが使うルール3:使用頻度によって書く場所を分けるうまく分けられずに、同じような記事が量産されることはある同じ情報が数か所に書いてあるのに、ある情報は1か所にだけ書いてある必要な情報が書いてあるところを参照できるようになっているすべての場所に漏れなく書いてあるどこにたどり着いても必要な情報を得られるように
どこに何を書くか (ルール) を決めましょう。• 対象読者で書く場所を決める• 機能で書く場所を決めるまとめそこに無いから無いですねと判断されないように、どこにたどり着いても必要な情報を得られるように気を配りましょう。• 必要な情報に誘導するために参照 (リンク) を使う• その情報が必要になるすべての場所に同じ内容をコピーする
ご清聴ありがとうございました！Twitter: @yazakimakoto
soracom
webmanagaer
circulation
gmofh_hr_team
toreta_recruit
toranoana
mitsu9
mntsq
srmarketing
hideki_ojima
libinc
kkosukeee
bravesoft
rasmusluckow
mraible
marktimemedia
holman
lauravandoore
eileencodes
thekraken
moore
denniskardys
bkeepers
bermonpainter
chriscoyier