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
930
「エンジニアのための ドキュメントライティング」書籍のすすめ / 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
660
EventBridgeの運用について
gorou_178
0
160
Stripe Appsと自サービスの連携作法
gorou_178
0
160
Laravelのsession設定を変えて 劇的にパフォーマンスを改善した話
gorou_178
0
1.5k
Stripeとアプリケーションの関係を可視化してみた
gorou_178
0
750
Stripeでの増税対応
gorou_178
0
700
Stripe+PHPでセキュアで安全な決済機能を作る
gorou_178
0
1.7k
Stripeを利用した決済機能をテストする
gorou_178
1
5.4k
tenpuでのStripe活用事例
gorou_178
0
300
Other Decks in Technology
See All in Technology
LINE-ChatGPT 倫理問題を整理する全力肯定彼氏くん [LuC4]に訪れたサービス開始以来の最大の危機
o_ob
2
150
とある事業会社にとっての Kaggler の魅力
hakubishin3
3
600
第45回 MLOps 勉強会 - ML Test Score を用いた機械学習システムの定量的なアセスメント
masatakashiwagi
3
310
受託開発でもアジャイル開発できました / Agile in Contract Development
takaking22
9
4.4k
普通の Web エンジニアのための様相論理入門 #yapcjapan / YAPC Hakodate 2024
ytaka23
5
1.5k
シェルとPerlの使い分け、 そういった思考の道具は、どこから来て、どこへゆくのか?v1.1.0
fmlorg
0
400
マーケットプレイス版Oracle WebCenter Content For OCI
oracle4engineer
PRO
2
240
Develop to Survive - YAPC::Hakodate 2024 Keynote
moznion
8
2.5k
【shownet.conf_】AI技術とUX監視の応用でShowNetの基盤を支えるモニタリングシステム
shownet
PRO
0
390
SageMaker学習のツボ / The Key Points of Learning SageMaker
cmhiranofumio
0
190
テストを楽に書きたい
tomorrowkey
1
180
クレジットカードを製造する技術
yutadayo
81
48k
Featured
See All Featured
Art, The Web, and Tiny UX
lynnandtonic
296
20k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
228
52k
Teambox: Starting and Learning
jrom
132
8.7k
Atom: Resistance is Futile
akmur
261
25k
Designing for humans not robots
tammielis
249
25k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
4
120
4 Signs Your Business is Dying
shpigford
180
21k
Into the Great Unknown - MozCon
thekraken
31
1.4k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
126
18k
Building Adaptive Systems
keathley
38
2.2k
Automating Front-end Workflow
addyosmani
1365
200k
Pencils Down: Stop Designing & Start Developing
hursman
119
11k
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) • ϐΫαʔɾΞχϝʔγϣϯɾελδΦͰ࠾༻͞Ε͍ͯΔϑΟʔυόοΫํ๏ • ʮݐઃతͳՃఏҊ͕Ͱ͖ΔͳΒɺΞΠσΞΛ൷ͯ͠Α͍ʯ •
τΠϧͷଘࡏΛཧղͰ͖ͳ͚ΕɺͦͷτΠϧΛࣗಈԽͯ͠ͳͤ͘ͳ͍ • ࣗಈԽͳͲযΒͣγϯϓϧͳํ๏Ͱ·ͣࢼͯ͠ΈΔ