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
850
「エンジニアのための ドキュメントライティング」書籍のすすめ / 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
520
EventBridgeの運用について
gorou_178
0
140
Stripe Appsと自サービスの連携作法
gorou_178
0
130
Laravelのsession設定を変えて 劇的にパフォーマンスを改善した話
gorou_178
0
1.3k
Stripeとアプリケーションの関係を可視化してみた
gorou_178
0
710
Stripeでの増税対応
gorou_178
0
660
Stripe+PHPでセキュアで安全な決済機能を作る
gorou_178
0
1.6k
Stripeを利用した決済機能をテストする
gorou_178
1
5.4k
tenpuでのStripe活用事例
gorou_178
0
280
Other Decks in Technology
See All in Technology
Flutter研修【MIXI 24新卒技術研修】
mixi_engineers
PRO
0
160
20240725 LLMによるDXのビジョンと、今何からやるべきか @Azure OpenAI Service Dev Day
nrryuya
3
1.1k
AutomatedLabを使って内部ペンテストを勉強しよう! -やられ社内ネットワークの自動構築-
n_etupirka
1
610
プレイドにおけるDatadog APMの活用方法
plaidtech
PRO
2
120
頼られるのが大好きな 皆さんへ - 支援相手との期待の合わせ方、突き放し方 -/For_people_who_like_to_be_relied_on
naitosatoshi
1
290
データ分析基盤を作ってみよう~設計編~
nrinetcom
PRO
1
110
データ分析を支える技術 生成AI再入門
ishikawa_satoru
0
380
年間一億円削減した時系列データベースのアーキテクチャ改善~不確実性の高いプロジェクトへの挑戦~
lycorptech_jp
PRO
3
2.9k
「単なる OAuth 2.0 を認証に使うと、車が通れるほどのどでかいセキュリティー・ホールができる」のか検証してみた
terara
0
380
地理情報とAPIのトレンド
nagix
0
160
Github Actions 로 Android 팀의 효율성 극대화
hadonghyun
0
160
データベース研修 DB基礎【MIXI 24新卒技術研修】
mixi_engineers
PRO
0
210
Featured
See All Featured
Visualization
eitanlees
139
14k
[Rails World 2023 - Day 1 Closing Keynote] - The Magic of Rails
eileencodes
17
1.5k
Typedesign – Prime Four
hannesfritz
37
2.2k
VelocityConf: Rendering Performance Case Studies
addyosmani
321
23k
Into the Great Unknown - MozCon
thekraken
20
1.3k
What's in a price? How to price your products and services
michaelherold
239
11k
How to train your dragon (web standard)
notwaldorf
79
5.5k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
90
47k
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
325
21k
Optimising Largest Contentful Paint
csswizardry
18
2.6k
Atom: Resistance is Futile
akmur
261
25k
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
24
1.8k
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) • ϐΫαʔɾΞχϝʔγϣϯɾελδΦͰ࠾༻͞Ε͍ͯΔϑΟʔυόοΫํ๏ • ʮݐઃతͳՃఏҊ͕Ͱ͖ΔͳΒɺΞΠσΞΛ൷ͯ͠Α͍ʯ •
τΠϧͷଘࡏΛཧղͰ͖ͳ͚ΕɺͦͷτΠϧΛࣗಈԽͯ͠ͳͤ͘ͳ͍ • ࣗಈԽͳͲযΒͣγϯϓϧͳํ๏Ͱ·ͣࢼͯ͠ΈΔ