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

「エンジニアのためのドキュメントライティング」書籍を読んでとても感動したので、一部抜粋してドキュメントを書くうえで大切なことなどをまとめました。

Transcript

1. ΤϯδχΞͷͨΊͷ υΩϡϝϯτϥΠςΟϯάॻ੶ͷ͢͢Ί 2023/06/24 PHPΧϯϑΝϨϯε෱Ԭ2023 @gorou_178
2. • @gorou_178 • BaaS(Bank as a Service)ͷ։ൃ • ϥϯχϯά • ίʔώʔͱϓϦϯ • θϧμ৽࡞ϓϨΠத ࣗݾ঺հ
3. ࠓ೔ͷΰʔϧ • υΩϡϝϯτΛॻ͘ͱ͖ͷେࣄͳϙΠϯτ͕ཧղͰ͖Δ • υΩϡϝϯτ੍࡞ʹ͓͍ͯ΋ɺސ٬ࢹ఺͕େࣄͰ͋Δ͜ͱ͕Θ ͔Δ
4. ΋͘͡ • ॻ੶ͷ঺հ • υΩϡϝϯτ؅ཧ • ಡΈखͱॻ͖खͷཧղ • υΩϡϝϯτͷ඼࣭ • υΩϡϝϯτϥΠςΟϯάͰେ੾ͳϙΠϯτ
5. ॻ੶ͷ঺հ
6. • ݪஶʮDocs for Developersʯͷ೔ຊޠ༁ • ࠓ೥3݄͝Ζग़൛ • ΤϯδχΞ͕࡞ͬͨΓɺར༻͢ΔυΩϡϝ ϯτʢAPI࢓༷ॻɺखॱॻͳͲʣʹର͢Δ ॻ͖ํͳͲΛઆ໌ͨ͠ຊ ΤϯδχΞͷͨΊͷυ ΩϡϝϯτϥΠςΟϯά
7. ॻ੶ͷ঺հ ΤϯδχΞ޲͚ʹॻ͔Εͨॻ੶ ͔͠͠ɺॻ͔Ε͍ͯΔυΩϡϝϯτͷ࡞੒ɾӡ༻ϊ΢ϋ΢͸͍Ζ Μͳਓ͕׆༻Ͱ͖Δʢͱࢲ͸ࢥͬͨʣ Ұ෦Λൈਮɾ·ͱΊͯ঺հ
8. υΩϡϝϯτ؅ཧ
9. υΩϡϝϯτ΋ϓϩμΫτ • ΈΜͳ͕΄͕͍ͬͯ͠ΔυΩϡϝϯτΛཧղʢԾઆݕূʣ • ·ͣ͸ॻ͍ͯΈΔʢ։ൃɾςετʣ • ಡΜͰ΋ΒͬͯϑΟʔυόοΫΛ΋Β͍վળ͢ΔʢϦϦʔεɺϨϏϡʔɺमਖ਼ɺݕূʣ • ཧղ͠΍͍͢Α͏ʹ࠶ฤू ≒ ϦϑΝΫλϦϯά • ϓϩμΫτ։ൃͷྲྀΕͱಉ͡
10. υΩϡϝϯτ΋ϓϩμΫτ • ΈΜͳ͕΄͕͍ͬͯ͠ΔυΩϡϝϯτΛཧղʢԾઆݕূʣ • ·ͣ͸ॻ͍ͯΈΔʢ։ൃɾςετʣ • ಡΜͰ΋ΒͬͯϑΟʔυόοΫΛ΋Β͍վળ͢ΔʢϦϦʔεɺϨϏϡʔɺमਖ਼ɺݕূʣ • ཧղ͠΍͍͢Α͏ʹ࠶ฤू ≒ ϦϑΝΫλϦϯά • ϓϩμΫτ։ൃͷྲྀΕͱಉ͡
11. υΩϡϝϯτͷސ٬ = ಡΈख ಡΈखͷࣄΛཧղ͢Δࣄ͕େ੾
12. ಡΈखͱॻ͖खͷཧղ
13. • ʮଞਓ͕ࣗ෼ͱಉ͡஌ࣝΛ͍࣋ͬͯΔʯ • ͱࢥ͍ࠐΜͰ͍Δೝ஌όΠΞεͷ͜ͱ • →ॻ͖ख͸͜ͷढ͍Λஅͪ੾Δඞཁ͕͋Δ ஌ࣝͷढ͍
14. • ಡΈख͸৘ใΛ୳ͯ͠υΩϡϝϯτʹͨͲ Γண͘ • ಡΈख͸ॻ͍ͯ͋Δ಺༰Λ΄ͱΜͲಡ·ͳ ͍ • ͜ͷໃ६Λཧղͯ͠͏·͘׆༻͢Δඞཁ͕ ͋Δ ಡΈखͷཧղ
15. Ͱ͸ɺͲͷΑ͏ʹॻ͘΂͖͔
16. υΩϡϝϯτ඼࣭ΛߴΊΔΑ͏ʹॻ͘
17. υΩϡϝϯτ඼࣭ • ػೳ඼࣭ͱߏ଄඼࣭ʹ෼ղ͞ΕΔ • ػೳ඼࣭: υΩϡϝϯτͷ໨త΍ΰʔϧ͕ୡ੒͞Ε͍ͯΔ͔Ͳ͏͔ • ߏ଄඼࣭: υΩϡϝϯτࣗମ͕͏·͘ߏ੒͞Ε͍ͯΔ͔Ͳ͏͔
18. ػೳ඼࣭ͱߏ଄඼࣭ • ػೳ඼࣭ • ໨త͕͋Δ͜ͱ • ΞΫηγϏϦςΟ͕͋Δ͜ͱ • ݟ͚ͭ΍͍͢͜ͱ • ਖ਼֬Ͱ͋Δ͜ͱ • ׬શͰ͋Δ͜ͱ • ߏ଄඼࣭ • Clear(໌֬ͳ) • Concise(؆ܿͳ) • Consistent(Ұ؏͍ͯ͠Δʣ υΩϡϝϯτͷ໨తΛୡ੒͠ͳ͚Ε͹ෆे෼ͳυΩϡϝϯτ →ͦͷͨΊɺػೳ඼࣭͕ΑΓॏཁ
19. ػೳ඼࣭ΛߴΊΔͨΊͷ େ੾ͳϙΠϯτ
20. 1. λΠτϧͱ๯಄͕େ੾
21. 1. λΠτϧͱ๯಄͕େ੾ • ࢒೦ͳ͕ΒυΩϡϝϯτ͸શͯಡ·Εͳ͍ • υΩϡϝϯτͷλΠτϧ͸ʮ͜ΕΛಡΉͱୡ੒Ͱ͖ΔΰʔϧΛཁ໿ͨ͠΋ͷʯʹ͢΂͖ • λΠτϧͱ๯಄Ͱʮ͜ΕΛಡΉ΂͖͔ʯ͕Θ͔Δ • ඦฉ͸Ұݟʹ͔ͣ͠ • Πϥετ΍ਤΛೖΕΔͱཧղ͠΍͍͢ • ΠϥετΛؚΉࢦࣔॻ vs ΠϥετΛؚ·ͳ͍ࢦࣔॻɺΠϥετΛؚΉࢦࣔॻͷํ͕໿3ഒ੒੷͕Α͔ͬͨ • ݟͨ໨ͷѱ͞ʹΑͬͯɺಡΈख͸ίϯςϯπ΁ͷڵຯΛࣦ͏͜ͱ͕͋Δ
22. 2. ݟग़͠͸ಓ͠Δ΂
23. 2. ݟग़͠͸ಓ͠Δ΂ • ಡΈख͸ͲΜͲΜಡΈඈ͹͢ • Ͱ͋Ε͹ɺݟग़͠ΛυΩϡϝϯτͷ໨త஍ʢಓ͠Δ΂ʣͱͯ͠ػೳͤ͞Δ • ඞཁͰͳ͍΋ͷ͸ಡΈඈ͹͠ɺඞཁͳ৘ใʹҰؾʹͨͲΓண͚Δ(VoiceOverͷݟग़͠δϟϯϓػೳ) • ݟग़͠ͰؾΛ͚ͭΔϙΠϯτ • ؆ܿɾ໌֬ɾ۩ମతʹ͢Δ • ࠷΋ॏཁͳ৘ใ͔Β࢝ΊΔ • ॏෳͷͳ͍ݟग़͠Λ࡞Δ • Ұ؏ੑΛอͭ
24. 3. Ұ؏ੑ
25. 3. Ұ؏ੑ • ༻ޠͷҰ؏ੑ • ༻ޠͷҰ؏ੑ͕ͳ͍ͱɺϓϩμΫτΛఏڙ͢Δ૊৫͕ɺ༻ޠͷఆٛʹ֬৴Λ͍࣋ͬͯͳ͍͜ͱΛࣔ͢ • Ϣʔβͷ৴པੑΛ௿Լͤ͞Δ • ݟग़͠ͷҰ؏ੑ • ॻ͖ํɺॱংͳͲʹ΋Ұ؏ੑΛ࣋ͨͤΔ͜ͱͰಡΈखΛ໎Θͤͳ͍ ͜ͷॻ੶શମͱͯ͠ʮҰ؏ੑʯ͕୔ࢁग़ͯ͘ΔͨΊͱͯ΋େ੾ͳϙΠϯτ →Ұ؏͍ͯ͠Δ͜ͱͰಡΈखͷཧղΛ๦͛ͳ͍
26. ·ͱΊ
27. ·ͱΊ • υΩϡϝϯτ͸ϓϩμΫτ։ൃͱಉ͡ʢυΩϡϝϯτ΋ϓϩμΫτ։ൃͷҰ෦ʣ • υΩϡϝϯτΛॻ͘ʹ͸ɺಡΈखͷཧղ͕ඞཁ • ސ٬ࢹ఺ɺେࣄ • ಡΈखΛ૝૾ͯ͠ɺཧղ͠΍͍͢υΩϡϝϯτΛॻ͍͍ͯ͜͏ • ʮཧղ͠΍͍͢ʯʹϋʔυϧΛײ͡ΔํɺԿͰ΋Α͍ͷͰͻͱ·ͣॻ͘ʂJust Do Itʂ • λΠτϧɾݟग़͠ɾҰ؏ੑ͕େࣄ • ΈΜͳͰυΩϡϝϯτΛҭͯΒΕΔπʔϧ΍αʔϏεΛར༻͢ΔͱΑΓΑͦ͞͏ • ͱͯ΋͓΋͠Ζ͍ͷͰॻ੶ΑΜͰΈ͍ͯͩ͘͞
28. Appendix • ҹ৅ʹ࢒ͬͨ෦෼ͷࡶͳϝϞ • ϓϥογϯά(plussing) • ϐΫαʔɾΞχϝʔγϣϯɾελδΦͰ࠾༻͞Ε͍ͯΔϑΟʔυόοΫํ๏ • ʮݐઃతͳ௥ՃఏҊ͕Ͱ͖ΔͳΒɺΞΠσΞΛ൷൑ͯ͠Α͍ʯ • τΠϧͷଘࡏΛཧղͰ͖ͳ͚Ε͹ɺͦͷτΠϧΛࣗಈԽͯ͠ͳͤ͘ͳ͍ • ࣗಈԽͳͲযΒͣγϯϓϧͳํ๏Ͱ·ͣ͸ࢼͯ͠ΈΔ