「エンジニアのためのドキュメントライティング」書籍のすすめ / phpconfuk 2023

by gorou_178

Slide 1

Slide 1 text

ΤϯδχΞͷͨΊͷ υΩϡϝϯτϥΠςΟϯάॻ੶ͷ͢͢Ί 2023/06/24 PHPΧϯϑΝϨϯε෱Ԭ2023 @gorou_178

Slide 2

Slide 2 text

• @gorou_178 • BaaS(Bank as a Service)ͷ։ൃ • ϥϯχϯά • ίʔώʔͱϓϦϯ • θϧμ৽࡞ϓϨΠத ࣗݾ঺հ

Slide 3

Slide 3 text

ࠓ೔ͷΰʔϧ • υΩϡϝϯτΛॻ͘ͱ͖ͷେࣄͳϙΠϯτ͕ཧղͰ͖Δ • υΩϡϝϯτ੍࡞ʹ͓͍ͯ΋ɺސ٬ࢹ఺͕େࣄͰ͋Δ͜ͱ͕Θ ͔Δ

Slide 4

Slide 4 text

΋͘͡ • ॻ੶ͷ঺հ • υΩϡϝϯτ؅ཧ • ಡΈखͱॻ͖खͷཧղ • υΩϡϝϯτͷ඼࣭ • υΩϡϝϯτϥΠςΟϯάͰେ੾ͳϙΠϯτ

Slide 5

Slide 5 text

ॻ੶ͷ঺հ

Slide 6

Slide 6 text

• ݪஶʮDocs for Developersʯͷ೔ຊޠ༁ • ࠓ೥3݄͝Ζग़൛ • ΤϯδχΞ͕࡞ͬͨΓɺར༻͢ΔυΩϡϝ ϯτʢAPI࢓༷ॻɺखॱॻͳͲʣʹର͢Δ ॻ͖ํͳͲΛઆ໌ͨ͠ຊ ΤϯδχΞͷͨΊͷυ ΩϡϝϯτϥΠςΟϯά

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

• ʮଞਓ͕ࣗ෼ͱಉ͡஌ࣝΛ͍࣋ͬͯΔʯ • ͱࢥ͍ࠐΜͰ͍Δೝ஌όΠΞεͷ͜ͱ • →ॻ͖ख͸͜ͷढ͍Λஅͪ੾Δඞཁ͕͋Δ ஌ࣝͷढ͍

Slide 14

Slide 14 text

• ಡΈख͸৘ใΛ୳ͯ͠υΩϡϝϯτʹͨͲ Γண͘ • ಡΈख͸ॻ͍ͯ͋Δ಺༰Λ΄ͱΜͲಡ·ͳ ͍ • ͜ͷໃ६Λཧղͯ͠͏·͘׆༻͢Δඞཁ͕ ͋Δ ಡΈखͷཧղ

Slide 15

Slide 15 text

Ͱ͸ɺͲͷΑ͏ʹॻ͘΂͖͔

Slide 16

Slide 16 text

υΩϡϝϯτ඼࣭ΛߴΊΔΑ͏ʹॻ͘

Slide 17

Slide 17 text

υΩϡϝϯτ඼࣭ • ػೳ඼࣭ͱߏ଄඼࣭ʹ෼ղ͞ΕΔ • ػೳ඼࣭: υΩϡϝϯτͷ໨త΍ΰʔϧ͕ୡ੒͞Ε͍ͯΔ͔Ͳ͏͔ • ߏ଄඼࣭: υΩϡϝϯτࣗମ͕͏·͘ߏ੒͞Ε͍ͯΔ͔Ͳ͏͔

Slide 18

Slide 18 text

ػೳ඼࣭ͱߏ଄඼࣭ • ػೳ඼࣭ • ໨త͕͋Δ͜ͱ • ΞΫηγϏϦςΟ͕͋Δ͜ͱ • ݟ͚ͭ΍͍͢͜ͱ • ਖ਼֬Ͱ͋Δ͜ͱ • ׬શͰ͋Δ͜ͱ • ߏ଄඼࣭ • Clear(໌֬ͳ) • Concise(؆ܿͳ) • Consistent(Ұ؏͍ͯ͠Δʣ υΩϡϝϯτͷ໨తΛୡ੒͠ͳ͚Ε͹ෆे෼ͳυΩϡϝϯτ →ͦͷͨΊɺػೳ඼࣭͕ΑΓॏཁ

Slide 19

Slide 19 text

ػೳ඼࣭ΛߴΊΔͨΊͷ େ੾ͳϙΠϯτ

Slide 20

Slide 20 text

1. λΠτϧͱ๯಄͕େ੾

Slide 21

Slide 21 text

1. λΠτϧͱ๯಄͕େ੾ • ࢒೦ͳ͕ΒυΩϡϝϯτ͸શͯಡ·Εͳ͍ • υΩϡϝϯτͷλΠτϧ͸ʮ͜ΕΛಡΉͱୡ੒Ͱ͖ΔΰʔϧΛཁ໿ͨ͠΋ͷʯʹ͢΂͖ • λΠτϧͱ๯಄Ͱʮ͜ΕΛಡΉ΂͖͔ʯ͕Θ͔Δ • ඦฉ͸Ұݟʹ͔ͣ͠ • Πϥετ΍ਤΛೖΕΔͱཧղ͠΍͍͢ • ΠϥετΛؚΉࢦࣔॻ vs ΠϥετΛؚ·ͳ͍ࢦࣔॻɺΠϥετΛؚΉࢦࣔॻͷํ͕໿3ഒ੒੷͕Α͔ͬͨ • ݟͨ໨ͷѱ͞ʹΑͬͯɺಡΈख͸ίϯςϯπ΁ͷڵຯΛࣦ͏͜ͱ͕͋Δ

Slide 22

Slide 22 text

2. ݟग़͠͸ಓ͠Δ΂

Slide 23

Slide 23 text

2. ݟग़͠͸ಓ͠Δ΂ • ಡΈख͸ͲΜͲΜಡΈඈ͹͢ • Ͱ͋Ε͹ɺݟग़͠ΛυΩϡϝϯτͷ໨త஍ʢಓ͠Δ΂ʣͱͯ͠ػೳͤ͞Δ • ඞཁͰͳ͍΋ͷ͸ಡΈඈ͹͠ɺඞཁͳ৘ใʹҰؾʹͨͲΓண͚Δ(VoiceOverͷݟग़͠δϟϯϓػೳ) • ݟग़͠ͰؾΛ͚ͭΔϙΠϯτ • ؆ܿɾ໌֬ɾ۩ମతʹ͢Δ • ࠷΋ॏཁͳ৘ใ͔Β࢝ΊΔ • ॏෳͷͳ͍ݟग़͠Λ࡞Δ • Ұ؏ੑΛอͭ

Slide 24

Slide 24 text

3. Ұ؏ੑ

Slide 25

Slide 25 text

3. Ұ؏ੑ • ༻ޠͷҰ؏ੑ • ༻ޠͷҰ؏ੑ͕ͳ͍ͱɺϓϩμΫτΛఏڙ͢Δ૊৫͕ɺ༻ޠͷఆٛʹ֬৴Λ͍࣋ͬͯͳ͍͜ͱΛࣔ͢ • Ϣʔβͷ৴པੑΛ௿Լͤ͞Δ • ݟग़͠ͷҰ؏ੑ • ॻ͖ํɺॱংͳͲʹ΋Ұ؏ੑΛ࣋ͨͤΔ͜ͱͰಡΈखΛ໎Θͤͳ͍ ͜ͷॻ੶શମͱͯ͠ʮҰ؏ੑʯ͕୔ࢁग़ͯ͘ΔͨΊͱͯ΋େ੾ͳϙΠϯτ →Ұ؏͍ͯ͠Δ͜ͱͰಡΈखͷཧղΛ๦͛ͳ͍

Slide 26

Slide 26 text

·ͱΊ

Slide 27

Slide 27 text

·ͱΊ • υΩϡϝϯτ͸ϓϩμΫτ։ൃͱಉ͡ʢυΩϡϝϯτ΋ϓϩμΫτ։ൃͷҰ෦ʣ • υΩϡϝϯτΛॻ͘ʹ͸ɺಡΈखͷཧղ͕ඞཁ • ސ٬ࢹ఺ɺେࣄ • ಡΈखΛ૝૾ͯ͠ɺཧղ͠΍͍͢υΩϡϝϯτΛॻ͍͍ͯ͜͏ • ʮཧղ͠΍͍͢ʯʹϋʔυϧΛײ͡ΔํɺԿͰ΋Α͍ͷͰͻͱ·ͣॻ͘ʂJust Do Itʂ • λΠτϧɾݟग़͠ɾҰ؏ੑ͕େࣄ • ΈΜͳͰυΩϡϝϯτΛҭͯΒΕΔπʔϧ΍αʔϏεΛར༻͢ΔͱΑΓΑͦ͞͏ • ͱͯ΋͓΋͠Ζ͍ͷͰॻ੶ΑΜͰΈ͍ͯͩ͘͞

Slide 28

Slide 28 text

Appendix • ҹ৅ʹ࢒ͬͨ෦෼ͷࡶͳϝϞ • ϓϥογϯά(plussing) • ϐΫαʔɾΞχϝʔγϣϯɾελδΦͰ࠾༻͞Ε͍ͯΔϑΟʔυόοΫํ๏ • ʮݐઃతͳ௥ՃఏҊ͕Ͱ͖ΔͳΒɺΞΠσΞΛ൷൑ͯ͠Α͍ʯ • τΠϧͷଘࡏΛཧղͰ͖ͳ͚Ε͹ɺͦͷτΠϧΛࣗಈԽͯ͠ͳͤ͘ͳ͍ • ࣗಈԽͳͲযΒͣγϯϓϧͳํ๏Ͱ·ͣ͸ࢼͯ͠ΈΔ