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

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

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

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

Transcript

1. 読み手を理解して より良いドキュメントを書こう LINE株式会社 開発４センター Developer Contentチーム 古木 亮太朗 2023.04.13
2. ࣗݾ঺հ ݹ໦ ྄ଠ࿕ -*/&גࣜձࣾ ςΫχΧϧϥΠλʔ • ೥-*/&ೖࣾ • ೥ʹࣾ಺ެืΛར༻͠ݱ৬ • ৬ྺ • ιϑτ΢ΣΞΤϯδχΞ • ޿ࠂ୅ཧళ • ෭ۀͰήʔϜࡶࢽͰϥΠλʔۀ • ΢ΣϒαʔϏεͷاըɾσΟϨΫλʔ • झຯ͸ίʔώʔͱؖࠃޠֶश
3. ΤϯδχΞͷͨΊͷυΩϡϝϯτϥΠςΟϯά ॏཁͳ͜ͱ͸ಡΈखͷཧղ ಡΈखͷཧղΛ׆༻͢Δ χʔζΛຬ͍ͨͤͯΔ͔Λݕূ͢Δ ·ͱΊ 01 02 03 04 05 Contents
4. ΤϯδχΞͷͨΊͷ υΩϡϝϯτϥΠςΟϯά
5. ΤϯδχΞͷͨΊͷ υΩϡϝϯτϥΠςΟϯά • ໊લͷͱ͓ΓϥΠςΟϯάʹؔ͢Δຊ • ʮ%PDT
   GPS
   %FWFMPQFSTʯͷ຋༁ॻ • ϥΠςΟϯάͷςΫχοΫ • υΩϡϝϯτͷॏཁੑɺܭըํ๏ • ݘͷ໐͖੠Λ຋༁͢ΔϓϩμΫτΛྫʹ υΩϡϝϯτͷܭըʙެ։ɺอकΛֶ΂Δ Ҿ༻ɿ+.".
   ೔ຊೳ཰ڠձϚωδϝϯτηϯλʔ IUUQTQVCKNBNDPKQCPPLCIUNM
6. $)"15&34 • $)"15&3
    ಡΈखͷཧղ • $)"15&3
    υΩϡϝϯτͷܭը • $)"15&3
    υΩϡϝϯτͷυϥϑτ • $)"15&3
    υΩϡϝϯτͷฤू • $)"15&3
    αϯϓϧίʔυͷ૊ΈࠐΈ • $)"15&3
    ϏδϡΞϧίϯςϯπͷ௥Ճ • $)"15&3
    υΩϡϝϯτͷެ։ • $)"15&3
    ϑΟʔυόοΫͷऩूͱ૊ΈࠐΈ • $)"15&3
    υΩϡϝϯτͷ඼࣭ଌఆ • $)"15&3
    υΩϡϝϯτͷߏ੒ • $)"15&3
    υΩϡϝϯτͷอकͱඇਪ঑Խ
7. $)"15&34 • $)"15&3
    ಡΈखͷཧղ • $)"15&3
    υΩϡϝϯτͷܭը • $)"15&3
    υΩϡϝϯτͷυϥϑτ • $)"15&3
    υΩϡϝϯτͷฤू • $)"15&3
    αϯϓϧίʔυͷ૊ΈࠐΈ • $)"15&3
    ϏδϡΞϧίϯςϯπͷ௥Ճ • $)"15&3
    υΩϡϝϯτͷެ։ • $)"15&3
    ϑΟʔυόοΫͷऩूͱ૊ΈࠐΈ • $)"15&3
    υΩϡϝϯτͷ඼࣭ଌఆ • $)"15&3
    υΩϡϝϯτͷߏ੒ • $)"15&3
    υΩϡϝϯτͷอकͱඇਪ঑Խ
8. ࢀߟ • 'PSLXFMM͞Μओ࠵ͷΦϯϥΠϯษڧձ • ຋༁Λ୲౰͞Εͨؠ੉͞Μʢ!JXBTIJʣ͕ొஃ • ॻ੶ͷ಺༰ͱϥΠςΟϯάʹؔΘΔςΫχοΫΛ঺հ IUUQTXXXZPVUVCFDPNXBUDI W+QGIJ-Z*
9. ॏཁͳ͜ͱ͸ಡΈखͷཧղ
10. ͳͥυΩϡϝϯτ͕ඞཁʁ • ͳͥυΩϡϝϯτΛॻ͘ඞཁ͕͋Δͷ͔ʁ • ͳͥϢʔβʔ͸υΩϡϝϯτΛಡΉඞཁ͕͋Δͷ͔ʁ
11. • ͳͥυΩϡϝϯτΛॻ͘ඞཁ͕͋Δͷ͔ʁ • ϢʔβʔʹԿ͔ͷλεΫΛ׬ྃͯ͠΄͍͠ • ͳͥϢʔβʔ͸υΩϡϝϯτΛಡΉඞཁ͕͋Δͷ͔ʁ • ϓϩμΫτΛ࢖ͬͯ՝୊Λղܾ͍ͨ͠ • Ϣʔβʔ͕ΰʔϧʹͨͲΓணͨ͘Ί • ৽نͷϢʔβʔ͕αʔϏεΛ࢖͍࢝ΊΔ͜ͱ͕Ͱ͖Δ ͳͥυΩϡϝϯτ͕ඞཁʁ
12. ͳͥಡΈखͷཧղ͕ॏཁ͔ • ϓϩμΫτͱϢʔβʔͷΰʔϧ͸ҧ͏͔΋͠Εͳ͍ • ϓϩμΫτɿϢʔβʔΛ֫ಘͯ͠αʔϏεΛάϩʔε͢Δ • ϢʔβʔɿϓϩμΫτΛ࢖ͬͯੜ׆Λศརʹ͍ͨ͠ • ҧͬͨͱͯ͠΋ॏͳΔ෦෼͸ඞͣ͋Δ • ॏͳΔ෦෼Λ୳ͯ͠ڞ௨ͷΰʔϧΛݟ͚ͭΔ • ͦͷͨΊʹ͸ʮϢʔβʔ΁ͷڞײʯ͕ඞཁ
13. ಡΈखͷཧղʹඞཁͳ͜ͱ • ಡΈख͕୭ͰɺԿΛ͍͔ͨ͠ΛΠϝʔδ͢Δ • ৘ใͷ੔ཧʢϝʔϧɺνϟοτͳͲʣ • αϙʔτνέοτͷ֬ೝɺϚʔέςΟϯά͔Βͷҙݟ • ಡΈखΛఆٛ͢Δ • ಡΈख͸͞·͟· 
    ࠷΋ॏཁͳϢʔβʔΛ༏ઌ • ಡΈखΛఆٛͯ͠ڞ௨ͷΰʔϧΛݟ͚ͭΔ
14. ʮ஌ࣝͷढ͍ʯʹؾΛ͚ͭΔ • ଞਓ͕ࣗ෼ͱಉ͡஌ࣝΛ͍࣋ͬͯΔͱࢥ͍ࠐΉ͜ͱ • ಡΈख͕͍࣋ͬͯΔ஌ࣝ͸͋ͳͨͱ͸ҧ͏ • ϓϩμΫτͷ஌ࣝ΍ɺυϝΠϯ஌ࣝ • ಡΈख͸جຊతͳ͜ͱΛղܾ͍͔ͨ͠΋ • ढ͍Λஅͪ੾Δʹ͸ɺϢʔβʔ΁ͷڞײ͕ඞཁ ೥୅ޙ൒ɺʮਓؒ͸ଞਓ͕ࣗ෼ͱಉ͡஌ࣝΛ΋͍ͬͯΔͱࢥ͍ࠐΜͰ͍Δʯ͜ͱΛϋʔόʔ υେֶͷܦࡁֶऀάϧʔϓ͕ൃݟ͠·ͨ͠ɻ൴Β͸͜ͷೝ஌όΠΞεΛʮ஌ࣝͷढ͍ʯͱ໊͚ͮ· ͨ͠ɻҾ༻ɿʰΤϯδχΞͷͨΊͷυΩϡϝϯτϥΠςΟϯάʱʢ1ʣ
15. ಡΈखͷཧղΛ׆༻͢Δ
16. ϢʔβʔχʔζͷΞ΢τϥΠϯΛ࡞Δ • ಡΈखΛఆٛ͢Δ͜ͱͰɺΰʔϧɺχʔζ͕ݟ͖͑ͯͨ • υΩϡϝϯτͰ౴͑Δඞཁ͕͋Γͦ͏ͳ࣭໰ϦετΛ࡞Δ • ͲΜͳϓϩμΫτ͔ʁ • ͲΜͳػೳ͕͋Δ͔ʁ • ͲΕ͘Β͍අ༻͕͔͔Δ͔ʁ • Ͳ͏͢Ε͹ಛఆͷ໰୊ΛղܾͰ͖Δ͔ʁ
17. ϢʔβʔχʔζͷΞ΢τϥΠϯΛ࡞Δ • ಡΈखΛఆٛ͢Δ͜ͱͰɺΰʔϧɺχʔζ͕ݟ͖͑ͯͨ • υΩϡϝϯτͰ౴͑Δඞཁ͕͋Γͦ͏ͳ࣭໰ϦετΛ࡞Δ • ͲΜͳϓϩμΫτ͔ʁ • ͲΜͳػೳ͕͋Δ͔ʁ • ͲΕ͘Β͍අ༻͕͔͔Δ͔ʁ • Ͳ͏͢Ε͹ಛఆͷ໰୊ΛղܾͰ͖Δ͔ʁ
18. ࠷ۙߋ৽ͨ͠υΩϡϝϯτ • ը૾ͳͲͷόΠφϦΛऔಘ͢Δ"1*ʹ͍ͭͯͷ'"2 • όΠφϦͷϑΝΠϧܗࣜͷ֬ೝํ๏͕Θ͔Βͳ͍ • ϨεϙϯεϔομʔΛ֬ೝ͢Δํ๏͕ॻ͔Ε͍ͯͳ͔ͬͨ • ݕ౼ͯ͠υΩϡϝϯτΛ௥Ճ
19. ࣗ෼ͷϢʔβʔମݧΛྫʹ • Ϣʔβʔମݧͱͯ͠خ͍͜͠ͱ͕͋ͬͨ • ߪೖͨ͠ίʔώʔ͕͏·͘ᔸΕΒΕͳ͍ • ళฮʹ໰͍߹ΘͤͯΈΔ͜ͱʹ • ஸೡʹରԠͯ͠΋Β͍ ඒຯ͘͠ᔸΕΒΕΔΑ͏ʹͳͬͨʂ "$*%$0''&& ʢΞγουίʔώʔʣ IUUQTBDJEDPGGFFTUPSFTKQ
20. ճ౴ʹΑͬͯຬͨ͞Εͨχʔζ ౰ళਪ঑ͷυϦοϓϨγϐ:PV5VCFʹಈըΛΞοϓ͠ ͓ͯΓ·͢ʂੋඇࢀߟʹ͍ͯͩ͘͠͞ˑ ͪͳΈʹɺ1"/"."
    Τεϝϥϧμ ϓϥΠϕʔτίϨ Ϋγϣϯ͸গ͠ૈΊ͕͓εεϝͰ͢ɻ ౰ళͰѻ͍ͬͯΔάϥΠϯμʔ&,
    ͕ਪ঑Ͱ͢ɻ ࢲࣗ਎ɺࣗ୐ͰλΠϜϞΞΛ࢖༻͓ͯ͠ΓΫϦοΫ Λ໨҆ʹ͓ͯ͠Γ·͢ɻͪ͜Β΋ੋඇࢀߟʹͯͩ͘͠ ͍͞ɻ ࣗ͝୐Ͱඒຯ͘͠ҿΊ·͢Α͏ʹɻ ϝʔϧΑΓҰ෦ൈਮ • ൨͖໨ͷ࿩͕Ϣʔβʔʢࣗ෼ʣ ʹͱͬͯॏཁͩͬͨ • ۩ମతͰΘ͔Γ΍͍͢಺༰ ಡΈखΛҙ͍ࣝͯ͠Δ
21. χʔζΛຬ͍ͨͤͯΔ͔Λݕূ͢Δ
22. Ϣʔβʔͷχʔζ͸ຬ͍ͨͤͯΔ͔ • ϢʔβʔͷχʔζΛຬ͍ͨͤͯΔ͔Λௐ΂Δ • Ϣʔβʔͷ੠ʹࣖΛ܏͚Δ • Ϣʔβʔ͔ΒͷϑΟʔυόοΫΛूΊΔ • ϑΟʔυόοΫΛߦಈʹͭͳ͛Δ
23. ϑΟʔυόοΫΛूΊΔ • Ϣʔβʔ͔ΒͷϑΟʔυόοΫΛूΊΔํ๏ • υΩϡϝϯτ΁ͷϑΟʔυόοΫΛ௚઀ड͚औΔ • υΩϡϝϯτʹର͢Δײ৘Λଌఆ͢Δ • αϙʔτνέοτΛϞχλϦϯά͢Δ • ϢʔβʔαʔϕΠ΍։ൃऀΞϯέʔτ • ϢʔβʔձͷઃཱɺΠϯλϏϡʔ
24. ϑΟʔυόοΫΛूΊΔ • Ϣʔβʔ͔ΒͷϑΟʔυόοΫΛूΊΔํ๏ • υΩϡϝϯτ΁ͷϑΟʔυόοΫΛ௚઀ड͚औΔ • υΩϡϝϯτʹର͢Δײ৘Λଌఆ͢Δ • αϙʔτνέοτΛϞχλϦϯά͢Δ • ϢʔβʔαʔϕΠ΍։ൃऀΞϯέʔτ • ϢʔβʔձͷઃཱɺΠϯλϏϡʔ
25. ϑΟʔυόοΫΛ௚઀ड͚औΔ • ެ։͞Ε͍ͯΔϖʔδʹର͢ΔϑΟʔυόοΫΛ௚઀ूΊΔ • վળ͢΂͖Օॴͷ۩ମతͳϑΟʔυόοΫ͕ಘΒΕΔ • ऩूํ๏ • ϝʔϧɺϑΥʔϜɺ(JU)VCΠγϡʔͳͲ • ऩूͷࡍʹ͸՝୊ͷςϯϓϨʔτ͕͋Δͱ˕
26. υΩϡϝϯτʹର͢Δײ৘ΛूΊΔ • ʮ͜ͷϖʔδ͸໾ʹཱͪ·͔ͨ͠ʁʯ • υΩϡϝϯτͷධՁ͕௿͍৔߹͸ϖʔδΛվળ • ධՁ͕ߴ͍ 
    ཧ༝͕Θ͔Ε͹࠶ݱՄೳ • ஫ҙ఺ • ׆༻͢Δʹ͸ଟ͘ͷσʔλ͕ඞཁ • ײ৘͸ίϯςΩετʹࠨӈ͞ΕΔ • τϥϒϧγϡʔςΟϯά͸ධՁ͕௿͘ͳΔ
27. -*/&
    %FWFMPQFSTαΠτͰ͸ • ϖʔδ͝ͱʹϑΟʔυόοΫΛૹΔػೳ • ʮ͍͍͑ʯͷ৔߹ʹҙݟΛҰॹʹૹΔ͜ ͱ͕Ͱ͖Δ • χʔζΛຬ͍ͨͯ͠Δ͔֬ೝͰ͖Δ
28. ࢀߟɿ-*/&
    %FWFMPQFST
    $PNNVOJUZ • ։ൃऀ͕ू·ΔίϛϡχςΟαΠτ • 2"͕͋ΓϓϩμΫτʹ͍ͭͯͷ࣭໰͕ଟ਺
29. ϑΟʔυόοΫΛूΊΔ • Ϣʔβʔ͔ΒͷϑΟʔυόοΫΛूΊΔํ๏ • υΩϡϝϯτ΁ͷϑΟʔυόοΫΛ௚઀ड͚औΔ • υΩϡϝϯτʹର͢Δײ৘Λଌఆ͢Δ • αϙʔτνέοτΛϞχλϦϯά͢Δ • ϢʔβʔαʔϕΠ΍։ൃऀΞϯέʔτ • ϢʔβʔձͷઃཱɺΠϯλϏϡʔ
30. αϙʔτνέοτΛϞχλϦϯά͢Δ • αϙʔτνʔϜ͸ϢʔβʔΛཧղ͢Δ্Ͱྑ͍ύʔτφʔ • ໰͍߹ΘͤͳͲͷ՝୊Λ؅ཧ • ಉ͡՝୊ʹԿ౓΋ૺ۰͍ͯ͠Δ͔΋͠Εͳ͍ • αϙʔτνʔϜͱີʹ࿈ܞ͢Δ • υΩϡϝϯτΛߋ৽ͯ͠՝୊Λղܾ͢Δ
31. ࢲͨͪͷνʔϜͰ͸ • ٕज़ࢧԉΛߦͳ͍ͬͯΔνʔϜͱڠۀ • ։ൃऀ͔Βͷ࣭໰ͳͲ͔ΒϑΟʔυόοΫ • ಺༰΍ॻ͖ํͷ૬ஊɺमਖ਼ํ਑ͷϨϏϡʔ • ؾܰʹҙݟΛฉ͚ΔʮಡΈखʯ͕ډΔ
32. ϑΟʔυόοΫΛߦಈʹܨ͛Δ • ϑΟʔυόοΫͷ಺༰͸͞·͟· • ༏ઌ౓෇͚΍࢓෼͚ͷϓϩηεʢτϦΞʔδʣ͕ඞཁ • ϦιʔεΛ༗ޮʹ͔ͭ͏ͨΊ • ॏཁͳ՝୊Λૣ͘ղܾ͢ΔͨΊ • ՝୊͕૿͑ଓ͚Δ͜ͱΛආ͚ΔͨΊ
33. ࢀߟɿௐࠪΛ஌ݟͱͯ͠·ͱΊΔ ʢུʣ ಘΒΕͨ஌ݟΛ͋ͱͷࣥචεςοϓͰ΋ࢀরͰ ͖Δܗʹ·ͱΊ͓ͯ͘͜ͱʹ͸Ձ஋͕͋Γ·͢ɻ Ϣʔβʔௐ͔ࠪΒ෼͔ͬͨ͜ͱΛ·ͱΊΔͨ Ίʹ໾ཱͭํ๏͕̏ͭ͋Γ·͢ɻ • Ϣʔβʔϖϧιφ • ϢʔβʔετʔϦʔ • ϢʔβʔδϟʔχʔϚοϓ Ҿ༻ɿ ʰΤϯδχΞͷͨΊͷυΩϡϝϯτϥΠςΟϯάʱ ʢ1ʣ • ݕূͨ͠ޙ͸ɺ஌ݟΛ·ͱΊͯ ͓͘ͱྑ͍ • ΍ͬͨ͜ͱ͕ͳ͍😭 • ͍͔ͭ΍ͬͯΈ͍ͨ • ຊॻͰ͸ϓϩμΫτͷެ։લ ͔ͭυΩϡϝϯτ࡞੒લ
34. ·ͱΊ
35. ·ͱΊ ಡΈखΛཧղ͢Δ͜ͱͰυΩϡϝϯτΛྑ͘͠Α͏ ڞײΛײͨ͡Ϣʔβʔ͸ϓϩμΫτΛ޷͖ʹͳΔ͖ͬͱ Ϣʔβʔ͔ΒͷϑΟʔυόοΫͷ࢓૊Έ͸େࣄ
36. THANK YOU