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

読み手を理解してより良いドキュメントを書こう / Write better documents...

読み手を理解してより良いドキュメントを書こう / Write better documents by understanding your audience

ドキュメントを書くときに、みなさんが気をつけていることは何でしょう? 情報の正確さや文章表現など、さまざまなことに気をつけていると思います。これらに加え、ドキュメントを書く上では、「読み手の理解」が重要です。今回は、2023年3月に発行された『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の内容を元に、どのようにして読み手を理解するか、そしてその重要性を一緒に考えていきたいと思います。

古木 亮太朗 / LINE株式会社 Developer Contentチーム テクニカルライター

この資料は以下イベントで発表した内容です。
https://line.connpass.com/event/279668/

LINE Developers

April 13, 2023
Tweet

More Decks by LINE Developers

Other Decks in Technology

Transcript

  1. ࣗݾ঺հ ݹ໦ ྄ଠ࿕ -*/&גࣜձࣾ ςΫχΧϧϥΠλʔ • ೥-*/&ೖࣾ • ೥ʹࣾ಺ެืΛར༻͠ݱ৬ •

    ৬ྺ • ιϑτ΢ΣΞΤϯδχΞ • ޿ࠂ୅ཧళ • ෭ۀͰήʔϜࡶࢽͰϥΠλʔۀ • ΢ΣϒαʔϏεͷاըɾσΟϨΫλʔ • झຯ͸ίʔώʔͱؖࠃޠֶश
  2. ΤϯδχΞͷͨΊͷ υΩϡϝϯτϥΠςΟϯά • ໊લͷͱ͓ΓϥΠςΟϯάʹؔ͢Δຊ • ʮ%PDTGPS%FWFMPQFSTʯͷ຋༁ॻ • ϥΠςΟϯάͷςΫχοΫ • υΩϡϝϯτͷॏཁੑɺܭըํ๏

    • ݘͷ໐͖੠Λ຋༁͢ΔϓϩμΫτΛྫʹ υΩϡϝϯτͷܭըʙެ։ɺอकΛֶ΂Δ Ҿ༻ɿ+.".೔ຊೳ཰ڠձϚωδϝϯτηϯλʔ IUUQTQVCKNBNDPKQCPPLCIUNM
  3. $)"15&34 • $)"15&3 ಡΈखͷཧղ • $)"15&3 υΩϡϝϯτͷܭը • $)"15&3 υΩϡϝϯτͷυϥϑτ

    • $)"15&3 υΩϡϝϯτͷฤू • $)"15&3 αϯϓϧίʔυͷ૊ΈࠐΈ • $)"15&3 ϏδϡΞϧίϯςϯπͷ௥Ճ • $)"15&3 υΩϡϝϯτͷެ։ • $)"15&3 ϑΟʔυόοΫͷऩूͱ૊ΈࠐΈ • $)"15&3 υΩϡϝϯτͷ඼࣭ଌఆ • $)"15&3 υΩϡϝϯτͷߏ੒ • $)"15&3 υΩϡϝϯτͷอकͱඇਪ঑Խ
  4. $)"15&34 • $)"15&3 ಡΈखͷཧղ • $)"15&3 υΩϡϝϯτͷܭը • $)"15&3 υΩϡϝϯτͷυϥϑτ

    • $)"15&3 υΩϡϝϯτͷฤू • $)"15&3 αϯϓϧίʔυͷ૊ΈࠐΈ • $)"15&3 ϏδϡΞϧίϯςϯπͷ௥Ճ • $)"15&3 υΩϡϝϯτͷެ։ • $)"15&3 ϑΟʔυόοΫͷऩूͱ૊ΈࠐΈ • $)"15&3 υΩϡϝϯτͷ඼࣭ଌఆ • $)"15&3 υΩϡϝϯτͷߏ੒ • $)"15&3 υΩϡϝϯτͷอकͱඇਪ঑Խ
  5. ʮ஌ࣝͷढ͍ʯʹؾΛ͚ͭΔ • ଞਓ͕ࣗ෼ͱಉ͡஌ࣝΛ͍࣋ͬͯΔͱࢥ͍ࠐΉ͜ͱ • ಡΈख͕͍࣋ͬͯΔ஌ࣝ͸͋ͳͨͱ͸ҧ͏ • ϓϩμΫτͷ஌ࣝ΍ɺυϝΠϯ஌ࣝ • ಡΈख͸جຊతͳ͜ͱΛղܾ͍͔ͨ͠΋ •

    ढ͍Λஅͪ੾Δʹ͸ɺϢʔβʔ΁ͷڞײ͕ඞཁ ೥୅ޙ൒ɺʮਓؒ͸ଞਓ͕ࣗ෼ͱಉ͡஌ࣝΛ΋͍ͬͯΔͱࢥ͍ࠐΜͰ͍Δʯ͜ͱΛϋʔόʔ υେֶͷܦࡁֶऀάϧʔϓ͕ൃݟ͠·ͨ͠ɻ൴Β͸͜ͷೝ஌όΠΞεΛʮ஌ࣝͷढ͍ʯͱ໊͚ͮ· ͨ͠ɻҾ༻ɿʰΤϯδχΞͷͨΊͷυΩϡϝϯτϥΠςΟϯάʱʢ1ʣ
  6. ࢀߟɿௐࠪΛ஌ݟͱͯ͠·ͱΊΔ ʢུʣ ಘΒΕͨ஌ݟΛ͋ͱͷࣥචεςοϓͰ΋ࢀরͰ ͖Δܗʹ·ͱΊ͓ͯ͘͜ͱʹ͸Ձ஋͕͋Γ·͢ɻ Ϣʔβʔௐ͔ࠪΒ෼͔ͬͨ͜ͱΛ·ͱΊΔͨ Ίʹ໾ཱͭํ๏͕̏ͭ͋Γ·͢ɻ • Ϣʔβʔϖϧιφ • ϢʔβʔετʔϦʔ

    • ϢʔβʔδϟʔχʔϚοϓ Ҿ༻ɿ ʰΤϯδχΞͷͨΊͷυΩϡϝϯτϥΠςΟϯάʱ ʢ1ʣ • ݕূͨ͠ޙ͸ɺ஌ݟΛ·ͱΊͯ ͓͘ͱྑ͍ • ΍ͬͨ͜ͱ͕ͳ͍😭 • ͍͔ͭ΍ͬͯΈ͍ͨ • ຊॻͰ͸ϓϩμΫτͷެ։લ ͔ͭυΩϡϝϯτ࡞੒લ