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
910
「エンジニアのための ドキュメントライティング」書籍のすすめ / 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
620
EventBridgeの運用について
gorou_178
0
160
Stripe Appsと自サービスの連携作法
gorou_178
0
160
Laravelのsession設定を変えて 劇的にパフォーマンスを改善した話
gorou_178
0
1.5k
Stripeとアプリケーションの関係を可視化してみた
gorou_178
0
740
Stripeでの増税対応
gorou_178
0
680
Stripe+PHPでセキュアで安全な決済機能を作る
gorou_178
0
1.6k
Stripeを利用した決済機能をテストする
gorou_178
1
5.4k
tenpuでのStripe活用事例
gorou_178
0
290
Other Decks in Technology
See All in Technology
不動産tech Product Night#2_AIことはじめ_GA橋本
takehikohashimoto
0
190
持続可能なソフトウェア開発を支える『GitHub CI/CD実践ガイド』
tmknom
8
1.4k
テスト”ケース”駆動開発 で手戻りをなくそう
ryohma0510
0
330
ナレッジグラフとLLMの相互利用
koujikozaki
0
430
プログラム検証入門
riru
6
880
Road to Single Activity
yurihondo
2
240
技術的負債解消の取り組みと専門チームのお話
bengo4com
0
340
watsonx.ai Dojo 環境準備について
oniak3ibm
PRO
0
350
不動産売買取引におけるAIの可能性とプロダクトでのAI活用
zabio3
0
270
どこよりも遅めなWinActor Ver.7.5.0 新機能紹介
tamai_63
0
210
GC24 Recap: Interface Internals
task4233
0
220
eBPFのこれまでとこれから
yutarohayakawa
10
3.2k
Featured
See All Featured
Designing on Purpose - Digital PM Summit 2013
jponch
114
6.8k
ParisWeb 2013: Learning to Love: Crash Course in Emotional UX Design
dotmariusz
109
6.9k
Thoughts on Productivity
jonyablonski
66
4.2k
Practical Orchestrator
shlominoach
185
10k
Reflections from 52 weeks, 52 projects
jeffersonlam
346
20k
Intergalactic Javascript Robots from Outer Space
tanoku
268
26k
Building Applications with DynamoDB
mza
90
6k
Happy Clients
brianwarren
96
6.6k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
663
120k
Statistics for Hackers
jakevdp
794
220k
Fashionably flexible responsive web design (full day workshop)
malarkey
401
65k
Why Our Code Smells
bkeepers
PRO
334
56k
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) • ϐΫαʔɾΞχϝʔγϣϯɾελδΦͰ࠾༻͞Ε͍ͯΔϑΟʔυόοΫํ๏ • ʮݐઃతͳՃఏҊ͕Ͱ͖ΔͳΒɺΞΠσΞΛ൷ͯ͠Α͍ʯ •
τΠϧͷଘࡏΛཧղͰ͖ͳ͚ΕɺͦͷτΠϧΛࣗಈԽͯ͠ͳͤ͘ͳ͍ • ࣗಈԽͳͲযΒͣγϯϓϧͳํ๏Ͱ·ͣࢼͯ͠ΈΔ