Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
「エンジニアのための ドキュメントライティング」書籍のすすめ / phpconfuk 2023
Search
gorou_178
June 24, 2023
Technology
2
1.1k
「エンジニアのための ドキュメントライティング」書籍のすすめ / phpconfuk 2023
「エンジニアのためのドキュメントライティング」書籍を読んでとても感動したので、一部抜粋してドキュメントを書くうえで大切なことなどをまとめました。
gorou_178
June 24, 2023
Tweet
Share
More Decks by gorou_178
See All by gorou_178
Spring Bootで作成したAPIテストのコスパを高めよう!
gorou_178
1
1.2k
EventBridgeの運用について
gorou_178
0
220
Stripe Appsと自サービスの連携作法
gorou_178
0
220
Laravelのsession設定を変えて 劇的にパフォーマンスを改善した話
gorou_178
0
2k
Stripeとアプリケーションの関係を可視化してみた
gorou_178
0
870
Stripeでの増税対応
gorou_178
0
810
Stripe+PHPでセキュアで安全な決済機能を作る
gorou_178
0
1.8k
Stripeを利用した決済機能をテストする
gorou_178
1
5.6k
tenpuでのStripe活用事例
gorou_178
0
340
Other Decks in Technology
See All in Technology
推し書籍📚 / Books and a QA Engineer
ak1210
0
120
Getting to Know Your Legacy (System) with AI-Driven Software Archeology (WeAreDevelopers World Congress 2025)
feststelltaste
1
180
ソフトウェアQAがハードウェアの人になったの
mineo_matsuya
3
180
20250708オープンエンドな探索と知識発見
sakana_ai
PRO
4
950
american aa airlines®️ USA Contact Numbers: Complete 2025 Support Guide
aaguide
0
500
Four Keysから始める信頼性の改善 - SRE NEXT 2025
ozakikota
0
240
第64回コンピュータビジョン勉強会「The PanAf-FGBG Dataset: Understanding the Impact of Backgrounds in Wildlife Behaviour Recognition」
x_ttyszk
0
230
shake-upを科学する
rsakata
7
960
Introduction to Bill One Development Engineer
sansan33
PRO
0
260
Bill One 開発エンジニア 紹介資料
sansan33
PRO
4
13k
Rethinking Incident Response: Context-Aware AI in Practice
rrreeeyyy
1
580
〜『世界中の家族のこころのインフラ』を目指して”次の10年”へ〜 SREが導いたグローバルサービスの信頼性向上戦略とその舞台裏 / Towards the Next Decade: Enhancing Global Service Reliability
kohbis
3
1.2k
Featured
See All Featured
Faster Mobile Websites
deanohume
307
31k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
138
34k
Being A Developer After 40
akosma
90
590k
Mobile First: as difficult as doing things right
swwweet
223
9.7k
Music & Morning Musume
bryan
46
6.7k
Automating Front-end Workflow
addyosmani
1370
200k
Building Applications with DynamoDB
mza
95
6.5k
BBQ
matthewcrist
89
9.7k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
233
17k
StorybookのUI Testing Handbookを読んだ
zakiyama
30
5.9k
Thoughts on Productivity
jonyablonski
69
4.7k
The Illustrated Children's Guide to Kubernetes
chrisshort
48
50k
Transcript
ΤϯδχΞͷͨΊͷ υΩϡϝϯτϥΠςΟϯάॻ੶ͷ͢͢Ί 2023/06/24 PHPΧϯϑΝϨϯεԬ2023 @gorou_178
• @gorou_178 • BaaS(Bank as a Service)ͷ։ൃ • ϥϯχϯά •
ίʔώʔͱϓϦϯ • θϧμ৽࡞ϓϨΠத ࣗݾհ
ࠓͷΰʔϧ • υΩϡϝϯτΛॻ͘ͱ͖ͷେࣄͳϙΠϯτ͕ཧղͰ͖Δ • υΩϡϝϯτ੍࡞ʹ͓͍ͯɺސ٬ࢹ͕େࣄͰ͋Δ͜ͱ͕Θ ͔Δ
͘͡ • ॻ੶ͷհ • υΩϡϝϯτཧ • ಡΈखͱॻ͖खͷཧղ • υΩϡϝϯτͷ࣭ •
υΩϡϝϯτϥΠςΟϯάͰେͳϙΠϯτ
ॻ੶ͷհ
• ݪஶʮDocs for Developersʯͷຊޠ༁ • ࠓ3݄͝Ζग़൛ • ΤϯδχΞ͕࡞ͬͨΓɺར༻͢ΔυΩϡϝ ϯτʢAPI༷ॻɺखॱॻͳͲʣʹର͢Δ ॻ͖ํͳͲΛઆ໌ͨ͠ຊ
ΤϯδχΞͷͨΊͷυ ΩϡϝϯτϥΠςΟϯά
ॻ੶ͷհ ΤϯδχΞ͚ʹॻ͔Εͨॻ੶ ͔͠͠ɺॻ͔Ε͍ͯΔυΩϡϝϯτͷ࡞ɾӡ༻ϊϋ͍Ζ Μͳਓ͕׆༻Ͱ͖Δʢͱࢲࢥͬͨʣ Ұ෦Λൈਮɾ·ͱΊͯհ
υΩϡϝϯτཧ
υΩϡϝϯτϓϩμΫτ • ΈΜͳ͕΄͕͍ͬͯ͠ΔυΩϡϝϯτΛཧղʢԾઆݕূʣ • ·ͣॻ͍ͯΈΔʢ։ൃɾςετʣ • ಡΜͰΒͬͯϑΟʔυόοΫΛΒ͍վળ͢ΔʢϦϦʔεɺϨϏϡʔɺमਖ਼ɺݕূʣ • ཧղ͍͢͠Α͏ʹ࠶ฤू ≒
ϦϑΝΫλϦϯά • ϓϩμΫτ։ൃͷྲྀΕͱಉ͡
υΩϡϝϯτϓϩμΫτ • ΈΜͳ͕΄͕͍ͬͯ͠ΔυΩϡϝϯτΛཧղʢԾઆݕূʣ • ·ͣॻ͍ͯΈΔʢ։ൃɾςετʣ • ಡΜͰΒͬͯϑΟʔυόοΫΛΒ͍վળ͢ΔʢϦϦʔεɺϨϏϡʔɺमਖ਼ɺݕূʣ • ཧղ͍͢͠Α͏ʹ࠶ฤू ≒
ϦϑΝΫλϦϯά • ϓϩμΫτ։ൃͷྲྀΕͱಉ͡
υΩϡϝϯτͷސ٬ = ಡΈख ಡΈखͷࣄΛཧղ͢Δࣄ͕େ
ಡΈखͱॻ͖खͷཧղ
• ʮଞਓ͕ࣗͱಉࣝ͡Λ͍࣋ͬͯΔʯ • ͱࢥ͍ࠐΜͰ͍ΔೝόΠΞεͷ͜ͱ • →ॻ͖ख͜ͷढ͍ΛஅͪΔඞཁ͕͋Δ ࣝͷढ͍
• ಡΈखใΛ୳ͯ͠υΩϡϝϯτʹͨͲ Γண͘ • ಡΈखॻ͍ͯ͋Δ༰Λ΄ͱΜͲಡ·ͳ ͍ • ͜ͷໃ६Λཧղͯ͠͏·͘׆༻͢Δඞཁ͕ ͋Δ ಡΈखͷཧղ
ͰɺͲͷΑ͏ʹॻ͖͔͘
υΩϡϝϯτ࣭ΛߴΊΔΑ͏ʹॻ͘
υΩϡϝϯτ࣭ • ػೳ࣭ͱߏ࣭ʹղ͞ΕΔ • ػೳ࣭: υΩϡϝϯτͷతΰʔϧ͕ୡ͞Ε͍ͯΔ͔Ͳ͏͔ • ߏ࣭: υΩϡϝϯτࣗମ͕͏·͘ߏ͞Ε͍ͯΔ͔Ͳ͏͔
ػೳ࣭ͱߏ࣭ • ػೳ࣭ • త͕͋Δ͜ͱ • ΞΫηγϏϦςΟ͕͋Δ͜ͱ • ݟ͚͍ͭ͢͜ͱ •
ਖ਼֬Ͱ͋Δ͜ͱ • શͰ͋Δ͜ͱ • ߏ࣭ • Clear(໌֬ͳ) • Concise(؆ܿͳ) • Consistent(Ұ؏͍ͯ͠Δʣ υΩϡϝϯτͷతΛୡ͠ͳ͚ΕෆेͳυΩϡϝϯτ →ͦͷͨΊɺػೳ࣭͕ΑΓॏཁ
ػೳ࣭ΛߴΊΔͨΊͷ େͳϙΠϯτ
1. λΠτϧͱ಄͕େ
1. λΠτϧͱ಄͕େ • ೦ͳ͕ΒυΩϡϝϯτશͯಡ·Εͳ͍ • υΩϡϝϯτͷλΠτϧʮ͜ΕΛಡΉͱୡͰ͖ΔΰʔϧΛཁͨ͠ͷʯʹ͖͢ • λΠτϧͱ಄Ͱʮ͜ΕΛಡΉ͖͔ʯ͕Θ͔Δ • ඦฉҰݟʹ͔ͣ͠
• ΠϥετਤΛೖΕΔͱཧղ͍͢͠ • ΠϥετΛؚΉࢦࣔॻ vs ΠϥετΛؚ·ͳ͍ࢦࣔॻɺΠϥετΛؚΉࢦࣔॻͷํ͕3ഒ͕Α͔ͬͨ • ݟͨͷѱ͞ʹΑͬͯɺಡΈखίϯςϯπͷڵຯΛࣦ͏͜ͱ͕͋Δ
2. ݟग़͠ಓ͠Δ
2. ݟग़͠ಓ͠Δ • ಡΈखͲΜͲΜಡΈඈ͢ • Ͱ͋Εɺݟग़͠ΛυΩϡϝϯτͷతʢಓ͠Δʣͱͯ͠ػೳͤ͞Δ • ඞཁͰͳ͍ͷಡΈඈ͠ɺඞཁͳใʹҰؾʹͨͲΓண͚Δ(VoiceOverͷݟग़͠δϟϯϓػೳ) • ݟग़͠ͰؾΛ͚ͭΔϙΠϯτ
• ؆ܿɾ໌֬ɾ۩ମతʹ͢Δ • ࠷ॏཁͳใ͔Β࢝ΊΔ • ॏෳͷͳ͍ݟग़͠Λ࡞Δ • Ұ؏ੑΛอͭ
3. Ұ؏ੑ
3. Ұ؏ੑ • ༻ޠͷҰ؏ੑ • ༻ޠͷҰ؏ੑ͕ͳ͍ͱɺϓϩμΫτΛఏڙ͢Δ৫͕ɺ༻ޠͷఆٛʹ֬৴Λ͍࣋ͬͯͳ͍͜ͱΛࣔ͢ • Ϣʔβͷ৴པੑΛԼͤ͞Δ • ݟग़͠ͷҰ؏ੑ
• ॻ͖ํɺॱংͳͲʹҰ؏ੑΛ࣋ͨͤΔ͜ͱͰಡΈखΛ໎Θͤͳ͍ ͜ͷॻ੶શମͱͯ͠ʮҰ؏ੑʯ͕ࢁग़ͯ͘ΔͨΊͱͯେͳϙΠϯτ →Ұ؏͍ͯ͠Δ͜ͱͰಡΈखͷཧղΛ͛ͳ͍
·ͱΊ
·ͱΊ • υΩϡϝϯτϓϩμΫτ։ൃͱಉ͡ʢυΩϡϝϯτϓϩμΫτ։ൃͷҰ෦ʣ • υΩϡϝϯτΛॻ͘ʹɺಡΈखͷཧղ͕ඞཁ • ސ٬ࢹɺେࣄ • ಡΈखΛ૾ͯ͠ɺཧղ͍͢͠υΩϡϝϯτΛॻ͍͍ͯ͜͏ •
ʮཧղ͍͢͠ʯʹϋʔυϧΛײ͡ΔํɺԿͰΑ͍ͷͰͻͱ·ͣॻ͘ʂJust Do Itʂ • λΠτϧɾݟग़͠ɾҰ؏ੑ͕େࣄ • ΈΜͳͰυΩϡϝϯτΛҭͯΒΕΔπʔϧαʔϏεΛར༻͢ΔͱΑΓΑͦ͞͏ • ͱ͓ͯ͠Ζ͍ͷͰॻ੶ΑΜͰΈ͍ͯͩ͘͞
Appendix • ҹʹͬͨ෦ͷࡶͳϝϞ • ϓϥογϯά(plussing) • ϐΫαʔɾΞχϝʔγϣϯɾελδΦͰ࠾༻͞Ε͍ͯΔϑΟʔυόοΫํ๏ • ʮݐઃతͳՃఏҊ͕Ͱ͖ΔͳΒɺΞΠσΞΛ൷ͯ͠Α͍ʯ •
τΠϧͷଘࡏΛཧղͰ͖ͳ͚ΕɺͦͷτΠϧΛࣗಈԽͯ͠ͳͤ͘ͳ͍ • ࣗಈԽͳͲযΒͣγϯϓϧͳํ๏Ͱ·ͣࢼͯ͠ΈΔ