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

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

Transcript

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

5. ॻ੶ͷ঺հ
   

   View Slide

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

   View Slide

7. ॻ੶ͷ঺հ
   ΤϯδχΞ޲͚ʹॻ͔Εͨॻ੶
   
   
   ͔͠͠ɺॻ͔Ε͍ͯΔυΩϡϝϯτͷ࡞੒ɾӡ༻ϊ΢ϋ΢͸͍Ζ
   Μͳਓ͕׆༻Ͱ͖Δʢͱࢲ͸ࢥͬͨʣ
   
   
   Ұ෦Λൈਮɾ·ͱΊͯ঺հ
   

   View Slide

8. υΩϡϝϯτ؅ཧ
   

   View Slide

9. υΩϡϝϯτ΋ϓϩμΫτ
   • ΈΜͳ͕΄͕͍ͬͯ͠ΔυΩϡϝϯτΛཧղʢԾઆݕূʣ
   
   
   • ·ͣ͸ॻ͍ͯΈΔʢ։ൃɾςετʣ
   
   
   • ಡΜͰ΋ΒͬͯϑΟʔυόοΫΛ΋Β͍վળ͢ΔʢϦϦʔεɺϨϏϡʔɺमਖ਼ɺݕূʣ
   
   
   • ཧղ͠΍͍͢Α͏ʹ࠶ฤू ≒ ϦϑΝΫλϦϯά
   
   
   • ϓϩμΫτ։ൃͷྲྀΕͱಉ͡
   

   View Slide

10. υΩϡϝϯτ΋ϓϩμΫτ
    • ΈΜͳ͕΄͕͍ͬͯ͠ΔυΩϡϝϯτΛཧղʢԾઆݕূʣ
    
    
    • ·ͣ͸ॻ͍ͯΈΔʢ։ൃɾςετʣ
    
    
    • ಡΜͰ΋ΒͬͯϑΟʔυόοΫΛ΋Β͍վળ͢ΔʢϦϦʔεɺϨϏϡʔɺमਖ਼ɺݕূʣ
    
    
    • ཧղ͠΍͍͢Α͏ʹ࠶ฤू ≒ ϦϑΝΫλϦϯά
    
    
    • ϓϩμΫτ։ൃͷྲྀΕͱಉ͡
    

    View Slide

11. υΩϡϝϯτͷސ٬ = ಡΈख
    
    
    ಡΈखͷࣄΛཧղ͢Δࣄ͕େ੾
    

    View Slide

12. ಡΈखͱॻ͖खͷཧղ
    

    View Slide

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

    View Slide

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

    View Slide

15. Ͱ͸ɺͲͷΑ͏ʹॻ͘΂͖͔
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

22. 2. ݟग़͠͸ಓ͠Δ΂
    

    View Slide

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

    View Slide

24. 3. Ұ؏ੑ
    

    View Slide

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

    View Slide

26. ·ͱΊ
    

    View Slide

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

    View Slide

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

    View Slide