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

by LINE Developers

Slide 1

Slide 1 text

読み手を理解してより良いドキュメントを書こう LINE株式会社開発４センター Developer Contentチーム古木亮太朗 2023.04.13

Slide 2

Slide 2 text

ࣗݾ঺հ ݹ໦ ྄ଠ࿕ -*/&גࣜձࣾ ςΫχΧϧϥΠλʔ • ೥-*/&ೖࣾ • ೥ʹࣾ಺ެืΛར༻͠ݱ৬ • ৬ྺ • ιϑτ΢ΣΞΤϯδχΞ • ޿ࠂ୅ཧళ • ෭ۀͰήʔϜࡶࢽͰϥΠλʔۀ • ΢ΣϒαʔϏεͷاըɾσΟϨΫλʔ • झຯ͸ίʔώʔͱؖࠃޠֶश

Slide 3

Slide 3 text

ΤϯδχΞͷͨΊͷυΩϡϝϯτϥΠςΟϯά ॏཁͳ͜ͱ͸ಡΈखͷཧղ ಡΈखͷཧղΛ׆༻͢Δ χʔζΛຬ͍ͨͤͯΔ͔Λݕূ͢Δ ·ͱΊ 01 02 03 04 05 Contents

Slide 4

Slide 4 text

ΤϯδχΞͷͨΊͷ υΩϡϝϯτϥΠςΟϯά

Slide 5

Slide 5 text

ΤϯδχΞͷͨΊͷ υΩϡϝϯτϥΠςΟϯά • ໊લͷͱ͓ΓϥΠςΟϯάʹؔ͢Δຊ • ʮ%PDTGPS%FWFMPQFSTʯͷ຋༁ॻ • ϥΠςΟϯάͷςΫχοΫ • υΩϡϝϯτͷॏཁੑɺܭըํ๏ • ݘͷ໐͖੠Λ຋༁͢ΔϓϩμΫτΛྫʹ υΩϡϝϯτͷܭըʙެ։ɺอकΛֶ΂Δ Ҿ༻ɿ+.".೔ຊೳ཰ڠձϚωδϝϯτηϯλʔ IUUQTQVCKNBNDPKQCPPLCIUNM

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

Slide 8

Slide 8 text

ࢀߟ • 'PSLXFMM͞Μओ࠵ͷΦϯϥΠϯษڧձ • ຋༁Λ୲౰͞Εͨؠ੉͞Μʢ!JXBTIJʣ͕ొஃ • ॻ੶ͷ಺༰ͱϥΠςΟϯάʹؔΘΔςΫχοΫΛ঺հ IUUQTXXXZPVUVCFDPNXBUDI W+QGIJ-Z*

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

ಡΈखͷཧղʹඞཁͳ͜ͱ • ಡΈख͕୭ͰɺԿΛ͍͔ͨ͠ΛΠϝʔδ͢Δ • ৘ใͷ੔ཧʢϝʔϧɺνϟοτͳͲʣ • αϙʔτνέοτͷ֬ೝɺϚʔέςΟϯά͔Βͷҙݟ • ಡΈखΛఆٛ͢Δ • ಡΈख͸͞·͟· ࠷΋ॏཁͳϢʔβʔΛ༏ઌ • ಡΈखΛఆٛͯ͠ڞ௨ͷΰʔϧΛݟ͚ͭΔ

Slide 14

Slide 14 text

ʮ஌ࣝͷढ͍ʯʹؾΛ͚ͭΔ • ଞਓ͕ࣗ෼ͱಉ͡஌ࣝΛ͍࣋ͬͯΔͱࢥ͍ࠐΉ͜ͱ • ಡΈख͕͍࣋ͬͯΔ஌ࣝ͸͋ͳͨͱ͸ҧ͏ • ϓϩμΫτͷ஌ࣝ΍ɺυϝΠϯ஌ࣝ • ಡΈख͸جຊతͳ͜ͱΛղܾ͍͔ͨ͠΋ • ढ͍Λஅͪ੾Δʹ͸ɺϢʔβʔ΁ͷڞײ͕ඞཁ ೥୅ޙ൒ɺʮਓؒ͸ଞਓ͕ࣗ෼ͱಉ͡஌ࣝΛ΋͍ͬͯΔͱࢥ͍ࠐΜͰ͍Δʯ͜ͱΛϋʔόʔ υେֶͷܦࡁֶऀάϧʔϓ͕ൃݟ͠·ͨ͠ɻ൴Β͸͜ͷೝ஌όΠΞεΛʮ஌ࣝͷढ͍ʯͱ໊͚ͮ· ͨ͠ɻҾ༻ɿʰΤϯδχΞͷͨΊͷυΩϡϝϯτϥΠςΟϯάʱʢ1ʣ

Slide 15

Slide 15 text

ಡΈखͷཧղΛ׆༻͢Δ

Slide 16

Slide 16 text

ϢʔβʔχʔζͷΞ΢τϥΠϯΛ࡞Δ • ಡΈखΛఆٛ͢Δ͜ͱͰɺΰʔϧɺχʔζ͕ݟ͖͑ͯͨ • υΩϡϝϯτͰ౴͑Δඞཁ͕͋Γͦ͏ͳ࣭໰ϦετΛ࡞Δ • ͲΜͳϓϩμΫτ͔ʁ • ͲΜͳػೳ͕͋Δ͔ʁ • ͲΕ͘Β͍අ༻͕͔͔Δ͔ʁ • Ͳ͏͢Ε͹ಛఆͷ໰୊ΛղܾͰ͖Δ͔ʁ

Slide 17

Slide 17 text

Slide 18

Slide 18 text

࠷ۙߋ৽ͨ͠υΩϡϝϯτ • ը૾ͳͲͷόΠφϦΛऔಘ͢Δ"1*ʹ͍ͭͯͷ'"2 • όΠφϦͷϑΝΠϧܗࣜͷ֬ೝํ๏͕Θ͔Βͳ͍ • ϨεϙϯεϔομʔΛ֬ೝ͢Δํ๏͕ॻ͔Ε͍ͯͳ͔ͬͨ • ݕ౼ͯ͠υΩϡϝϯτΛ௥Ճ

Slide 19

Slide 19 text

ࣗ෼ͷϢʔβʔମݧΛྫʹ • Ϣʔβʔମݧͱͯ͠خ͍͜͠ͱ͕͋ͬͨ • ߪೖͨ͠ίʔώʔ͕͏·͘ᔸΕΒΕͳ͍ • ళฮʹ໰͍߹ΘͤͯΈΔ͜ͱʹ • ஸೡʹରԠͯ͠΋Β͍ ඒຯ͘͠ᔸΕΒΕΔΑ͏ʹͳͬͨʂ "$*%$0''&& ʢΞγουίʔώʔʣ IUUQTBDJEDPGGFFTUPSFTKQ

Slide 20

Slide 20 text

ճ౴ʹΑͬͯຬͨ͞Εͨχʔζ ౰ళਪ঑ͷυϦοϓϨγϐ:PV5VCFʹಈըΛΞοϓ͠ ͓ͯΓ·͢ʂੋඇࢀߟʹ͍ͯͩ͘͠͞ˑ ͪͳΈʹɺ1"/"."Τεϝϥϧμ ϓϥΠϕʔτίϨ Ϋγϣϯ͸গ͠ૈΊ͕͓εεϝͰ͢ɻ ౰ళͰѻ͍ͬͯΔάϥΠϯμʔ&,͕ਪ঑Ͱ͢ɻ ࢲࣗ਎ɺࣗ୐ͰλΠϜϞΞΛ࢖༻͓ͯ͠ΓΫϦοΫ Λ໨҆ʹ͓ͯ͠Γ·͢ɻͪ͜Β΋ੋඇࢀߟʹͯͩ͘͠ ͍͞ɻ ࣗ͝୐Ͱඒຯ͘͠ҿΊ·͢Α͏ʹɻ ϝʔϧΑΓҰ෦ൈਮ • ൨͖໨ͷ࿩͕Ϣʔβʔʢࣗ෼ʣ ʹͱͬͯॏཁͩͬͨ • ۩ମతͰΘ͔Γ΍͍͢಺༰ ಡΈखΛҙ͍ࣝͯ͠Δ

Slide 21

Slide 21 text

χʔζΛຬ͍ͨͤͯΔ͔Λݕূ͢Δ

Slide 22

Slide 22 text

Ϣʔβʔͷχʔζ͸ຬ͍ͨͤͯΔ͔ • ϢʔβʔͷχʔζΛຬ͍ͨͤͯΔ͔Λௐ΂Δ • Ϣʔβʔͷ੠ʹࣖΛ܏͚Δ • Ϣʔβʔ͔ΒͷϑΟʔυόοΫΛूΊΔ • ϑΟʔυόοΫΛߦಈʹͭͳ͛Δ

Slide 23

Slide 23 text

ϑΟʔυόοΫΛूΊΔ • Ϣʔβʔ͔ΒͷϑΟʔυόοΫΛूΊΔํ๏ • υΩϡϝϯτ΁ͷϑΟʔυόοΫΛ௚઀ड͚औΔ • υΩϡϝϯτʹର͢Δײ৘Λଌఆ͢Δ • αϙʔτνέοτΛϞχλϦϯά͢Δ • ϢʔβʔαʔϕΠ΍։ൃऀΞϯέʔτ • ϢʔβʔձͷઃཱɺΠϯλϏϡʔ

Slide 24

Slide 24 text

Slide 25

Slide 25 text

ϑΟʔυόοΫΛ௚઀ड͚औΔ • ެ։͞Ε͍ͯΔϖʔδʹର͢ΔϑΟʔυόοΫΛ௚઀ूΊΔ • վળ͢΂͖Օॴͷ۩ମతͳϑΟʔυόοΫ͕ಘΒΕΔ • ऩूํ๏ • ϝʔϧɺϑΥʔϜɺ(JU)VCΠγϡʔͳͲ • ऩूͷࡍʹ͸՝୊ͷςϯϓϨʔτ͕͋Δͱ˕

Slide 26

Slide 26 text

υΩϡϝϯτʹର͢Δײ৘ΛूΊΔ • ʮ͜ͷϖʔδ͸໾ʹཱͪ·͔ͨ͠ʁʯ • υΩϡϝϯτͷධՁ͕௿͍৔߹͸ϖʔδΛվળ • ධՁ͕ߴ͍ ཧ༝͕Θ͔Ε͹࠶ݱՄೳ • ஫ҙ఺ • ׆༻͢Δʹ͸ଟ͘ͷσʔλ͕ඞཁ • ײ৘͸ίϯςΩετʹࠨӈ͞ΕΔ • τϥϒϧγϡʔςΟϯά͸ධՁ͕௿͘ͳΔ

Slide 27

Slide 27 text

-*/&%FWFMPQFSTαΠτͰ͸ • ϖʔδ͝ͱʹϑΟʔυόοΫΛૹΔػೳ • ʮ͍͍͑ʯͷ৔߹ʹҙݟΛҰॹʹૹΔ͜ ͱ͕Ͱ͖Δ • χʔζΛຬ͍ͨͯ͠Δ͔֬ೝͰ͖Δ

Slide 28

Slide 28 text

ࢀߟɿ-*/&%FWFMPQFST$PNNVOJUZ • ։ൃऀ͕ू·ΔίϛϡχςΟαΠτ • 2"͕͋ΓϓϩμΫτʹ͍ͭͯͷ࣭໰͕ଟ਺

Slide 29

Slide 29 text

Slide 30

Slide 30 text

αϙʔτνέοτΛϞχλϦϯά͢Δ • αϙʔτνʔϜ͸ϢʔβʔΛཧղ͢Δ্Ͱྑ͍ύʔτφʔ • ໰͍߹ΘͤͳͲͷ՝୊Λ؅ཧ • ಉ͡՝୊ʹԿ౓΋ૺ۰͍ͯ͠Δ͔΋͠Εͳ͍ • αϙʔτνʔϜͱີʹ࿈ܞ͢Δ • υΩϡϝϯτΛߋ৽ͯ͠՝୊Λղܾ͢Δ

Slide 31

Slide 31 text

ࢲͨͪͷνʔϜͰ͸ • ٕज़ࢧԉΛߦͳ͍ͬͯΔνʔϜͱڠۀ • ։ൃऀ͔Βͷ࣭໰ͳͲ͔ΒϑΟʔυόοΫ • ಺༰΍ॻ͖ํͷ૬ஊɺमਖ਼ํ਑ͷϨϏϡʔ • ؾܰʹҙݟΛฉ͚ΔʮಡΈखʯ͕ډΔ

Slide 32

Slide 32 text

ϑΟʔυόοΫΛߦಈʹܨ͛Δ • ϑΟʔυόοΫͷ಺༰͸͞·͟· • ༏ઌ౓෇͚΍࢓෼͚ͷϓϩηεʢτϦΞʔδʣ͕ඞཁ • ϦιʔεΛ༗ޮʹ͔ͭ͏ͨΊ • ॏཁͳ՝୊Λૣ͘ղܾ͢ΔͨΊ • ՝୊͕૿͑ଓ͚Δ͜ͱΛආ͚ΔͨΊ

Slide 33

Slide 33 text

ࢀߟɿௐࠪΛ஌ݟͱͯ͠·ͱΊΔ ʢུʣ ಘΒΕͨ஌ݟΛ͋ͱͷࣥචεςοϓͰ΋ࢀরͰ ͖Δܗʹ·ͱΊ͓ͯ͘͜ͱʹ͸Ձ஋͕͋Γ·͢ɻ Ϣʔβʔௐ͔ࠪΒ෼͔ͬͨ͜ͱΛ·ͱΊΔͨ Ίʹ໾ཱͭํ๏͕̏ͭ͋Γ·͢ɻ • Ϣʔβʔϖϧιφ • ϢʔβʔετʔϦʔ • ϢʔβʔδϟʔχʔϚοϓ Ҿ༻ɿ ʰΤϯδχΞͷͨΊͷυΩϡϝϯτϥΠςΟϯάʱ ʢ1ʣ • ݕূͨ͠ޙ͸ɺ஌ݟΛ·ͱΊͯ ͓͘ͱྑ͍ • ΍ͬͨ͜ͱ͕ͳ͍😭 • ͍͔ͭ΍ͬͯΈ͍ͨ • ຊॻͰ͸ϓϩμΫτͷެ։લ ͔ͭυΩϡϝϯτ࡞੒લ

Slide 34

Slide 34 text

·ͱΊ

Slide 35

Slide 35 text

·ͱΊ ಡΈखΛཧղ͢Δ͜ͱͰυΩϡϝϯτΛྑ͘͠Α͏ ڞײΛײͨ͡Ϣʔβʔ͸ϓϩμΫτΛ޷͖ʹͳΔ͖ͬͱ Ϣʔβʔ͔ΒͷϑΟʔυόοΫͷ࢓૊Έ͸େࣄ

Slide 36

Slide 36 text

THANK YOU